Troubleshooting

401 Unauthorized

Cause: Token is missing, expired, or lacks the export:markdown:custom scope.

Solutions:

  • Verify the Authorization header format: Bearer YOUR_ACCESS_TOKEN
  • Refresh your access token — tokens expire after 1 hour
  • Confirm your OAuth integration includes both export:markdown:custom and read:forge-app:confluence scopes
  • Re-authorize if you added scopes after your last authorization (scopes are locked at consent time)

403 Forbidden

Cause: App REST APIs not enabled on the site, or the OAuth integration is connected to the wrong Forge app or environment.

Solutions:

  • Ask a site admin to enable App REST APIs in admin.atlassian.com → Connected Apps → Markdown Exporter → Details tab
  • Verify your OAuth integration is connected to Markdown Exporter for Confluence (not another app)
  • Check that the ENV_ID in your URL matches the environment where the app is installed (dev / staging / production)

404 No pages found

Cause: The spaceKey or pageId does not exist or is inaccessible to the app.

Solutions:

  • Confirm the spaceKey is correct (visible in Confluence space settings)
  • Confirm the pageId is correct (visible in the page URL or via Confluence REST API)
  • Ensure the app has access to the space — check that Markdown Exporter is installed on the site where the space lives

500 / Invocation failed

Cause: Unexpected server error in the Forge function.

Solutions:

  • Retry the request — transient errors are common under load
  • Check Forge logs for details:
forge logs -e production
  • If the error persists, contact support with the exportId from the response (if available)

Refresh token stopped working

Cause: An old refresh token was reused after a newer one had already been issued. Atlassian invalidates the entire token chain when this happens.

Solution: Re-authorize from scratch — repeat Step 3 from Getting Started to get a fresh token pair. Going forward, always save and use the latest refresh token returned by each refresh call.

ZIP is empty or page count is 0

Cause: The export matched no accessible pages.

Solutions:

  • When using spaceKey, verify the space has pages visible to the OAuth user
  • When using pageId with bulkExport: true, verify the page has children
  • Check maxPages — if set to 1, only the root page is exported with no descendants

Response body exceeds limit

Cause: The export exceeded the 5 MB Forge platform response limit.

Solutions:

  • Reduce maxPages and paginate by exporting subtrees using specific pageId values
  • Disable includeAttachments to reduce response size
  • Split large spaces into multiple requests