Troubleshooting

Find your symptom below. If none matches, see "How do I report a bug or ask for help?" in the FAQ.

The macro shows a parser error with a line number

The message identifies the line and, usually, the column where the parser gave up, for example YAMLException: bad indentation of a mapping entry (12:5). Open the file in an editor that shows line numbers and go to that spot. The most frequent causes:

• Indentation. YAML uses spaces, never tabs. A key that is one space off is enough to break the document.
• Unquoted special characters. A value containing : followed by a space, a leading *, &, @, or % needs quotes. Version strings such as 1.0 may need quotes ("1.0") if you want them kept as text.
• Invalid JSON. Trailing commas, single quotes, and comments are not allowed in JSON.
• Altered text. Smart quotes and non-breaking spaces can sneak in when copying from web pages or documents. Paste from the original file.
• Wrong document. The root must contain openapi: 3.x.x or swagger: "2.0".

The line number refers to the text the macro received, so if you pasted it, count from the first pasted line.

Tip: validate in your pipeline with npx @redocly/cli lint openapi.yaml before uploading.

"No attachment found"

The macro is set to attachment mode but cannot locate the file. Check each of these:

1. The file is attached to this page. Other pages' attachments are not listed.
2. The extension is .yaml, .yml, or .json.
3. The file was not deleted or renamed after you selected it. Reselect it in the macro.
4. For a pinned version, that version still exists. Deleting a version removes it. Switch to "Always latest" or pick another version.

If you copied or moved the page, open the macro and choose the file again.

Permission errors

The macro reads the attachment with the viewer's own permissions. If someone sees an error where others see the spec:

• They need permission to view the page. Page restrictions apply to attachments, so a restricted page hides the spec from everyone not on the list.
• For uploads from CI, the account behind the token needs permission to add attachments to the page. See CI push.

The fix is to grant access to the page, not to change the macro.

The macro does not render in a template or an unpublished draft

• Page templates: a template is not a real page, so it has no attachments to read. Attachment mode cannot work there. Use paste mode in templates, or tell authors to select the attachment after they create a page from the template.
• Unpublished drafts: the preview can be limited until the page has been published at least once. If the editor shows nothing, publish the page (you can restrict it to yourself first), then check again.

The spec updated in Confluence but readers see the old version

• Reload the page. The macro reads the file when the page loads.
• Check the macro is on "Always latest" and not pinned.
• Check that the upload used the same file name. A different name creates a second attachment, and the macro keeps showing the first.

Rendering is slow or the page freezes

Very large specs (many thousands of operations, or megabytes of schemas) are heavy to display in a browser.

1. Keep operations collapsed, and use tag filtering and search rather than expanding everything.
2. Split the API into one spec and one page per service or domain.
3. Remove unused schemas and very large inline examples before upload. Embedded base64 files in examples are a frequent cause of multi-megabyte specs.

If a spec under a few MB is still slow, send it to support (a trimmed copy is fine) and we will investigate.