Troubleshooting

What Apifolio's messages mean and how to fix the most common problems with OpenAPI and Swagger docs in Confluence.

Messages in the macro

"The API file was not found" ("The file … is no longer attached to this page.") The file was deleted, or replaced by a file with another name. Attach the file again, or edit the macro and pick the new file. A file that was only renamed is still found.

"The API file could not be read" The spec has a syntax error. The message shows the line, a few lines of the file around it with a mark under the column, and a hint for the usual causes: a tab instead of spaces, a value with ": " that needs quotes, an unclosed quote, a comma before } or ] in JSON. Fix the file at that line. The preview in the macro dialog shows the same error while you edit.

"This file is not an OpenAPI or Swagger document" The file has no openapi or swagger field at the top. The message lists the top-level keys it found: check that you picked the right file.

"This is an AsyncAPI document" Apifolio shows OpenAPI 3.x and Swagger 2.0 files only. See What Apifolio does not do.

"You don't have access to the source page" The macro shows a spec attached to another page that you can't open. Click Open source page to go to that page and ask for access, or ask the page owner to attach the file to a page you can open.

"You don't have permission to see this file" Your Confluence permissions don't allow you to read the attachment. Ask the page owner.

"Sign in to see this API documentation" Anonymous visitors can only see specs attached to the same page, up to about 4 MB. See Public spaces.

"Confluence is busy" or "Confluence is temporarily unavailable" Apifolio retries these answers by itself, so Confluence is still busy. Click Try again in a moment: only the macro reloads, not the page.

"The API file is too large" The limit is 25 MB (about 4 MB for anonymous visitors). Make the file smaller, for example by removing very large examples, or document parts of the API in separate spec files.

"No endpoints to show" The macro's sections, endpoints or paths filters hide every endpoint of the file, for example after a new version renamed the sections. Edit the macro and change the filters.

"This file defines data models only" The file has schemas and no endpoints, like a shared data dictionary. Apifolio shows its data models.

The reference lists other files and a tip on bundling The paths of the spec are references to other files, which Apifolio never fetches. Bundle the spec into one file and attach that file.

"This endpoint could not be displayed" (or another part) One part of the spec could not be rendered; the rest of the reference, the navigation and search still work. Write to support with the endpoint and, if you can, the part of the spec that describes it.

"Apifolio is not active on this site", or a locked list of endpoints The site's Apifolio subscription is not active. A site admin can renew it in Confluence settings → Manage apps.

Other problems

The macro shows an error on a page that was never published. Publish the page once: until then, Confluence may not let apps read the page's attachments. The macro dialog works before the first publish.

The docs show an old version. Reload the page: Apifolio loads the latest version of the file on every fresh load. The footer shows the version and when it changed.

Confluence search doesn't find new endpoints. The search index is refreshed when the macro is saved. Open the macro and click Save; while editing the page, a note above the macro tells you when this is needed. For very large APIs, check the coverage line in the dialog. See Confluence search.

The PDF shows only tables of endpoints. The macro shows more than 250 endpoints. Narrow it to fewer sections or endpoints. See Export.

The PDF ends with a note that some endpoints have fewer details. The export reached its size limit. Narrow the macro to fewer endpoints to export every detail.

A public link shows nothing where the macro is. Confluence public links don't show app content. Use ⋯ → Copy as Confluence content. See Public spaces.

Edit request says the JSON body is not valid. The message gives the line and column. Until you fix it, the code samples keep the last valid body.

"That link is from another Confluence site" under Another page A macro can only show files of the same Confluence site. Attach a copy of the spec to a page of this site.

The old app's macro is not offered for import. The dialog reads the published version of the page and recognises the macros listed in Moving from another app. Publish the page, or move it by hand as described there.

Still stuck? Write to [email protected] with the page link and a screenshot.

View as Markdown