Troubleshoot a portal

Start with the last successful stage: source connection, portal editing, preview, publishing, access, or domain routing. The checks below avoid changing unrelated parts of the portal.

A spec does not appear

Confirm the GitHub App still has access to the repository.
Confirm the selected branch exists.
Confirm the file matches the configured pattern and extension.
Validate that the file is parseable OpenAPI 3.x YAML or JSON.
Run Sync now and inspect its status.

For pasted specs, use a stable filename and paste the complete document rather than a fragment.

The latest spec differs from the live portal

This is expected after a sync. Latest is editable source state; Published is the revision pinned in the live build. Review the affected pages and publish a new build when ready.

Portal JSON import fails

Check that:

apifleet_portal is 1.
name is non-empty and pages contains at least one page.
Page slugs are unique.
Every block type and enum is supported.
Every specs filename already exists in the destination workspace.
endpoint and schema blocks reference a filename listed in specs.
The document is below the published size and page/block limits.

Unknown block types are rejected. Unknown configuration fields may be dropped, so validate the exported result after import.

An endpoint block is empty or wrong

Confirm its spec_file matches an attached spec exactly. Use op:<operationId> when the operation has a stable ID; otherwise use op:<METHOD> <path>. Export a generated portal to copy a known-good address.

The page may be hidden, assigned to another group, or not yet added to the custom navigation. Open navigation controls, add the page to the intended group, and preview again. A hidden page can still be accessible by direct URL.

A restricted page is visible or inaccessible

Check both portal-level access and page-level visible_to. Then test in a new signed-out session and as a member of the intended organization. Do not use the presence of a navigation item as an access test.

Publish fails

Keep the previous live build in place. Check for missing attached specs, invalid block references, unavailable assets, and a failed background job. Retry only after correcting the reported cause; repeated publishes of the same draft are unlikely to fix invalid content.

The custom domain does not verify

Copy the record name and value exactly.
Remove accidental duplication of the root domain in the record name.
Confirm the record is publicly resolvable.
If using Cloudflare, temporarily set the record to DNS only.
Allow for DNS cache and certificate provisioning time.

After verification, ensure the final CNAME points to the hostname API Fleet provides. Test HTTPS and a nested page, not only the root URL.

Custom CSS breaks the portal

Remove or narrow the newest rule. custom_css is global and can hide or move core controls. It may also fetch external URLs. Prefer theme tokens and keep an export of the last working portal document before advanced CSS changes.

Still blocked

Email hello@apifleet.io with:

Workspace and portal names (never credentials).
The page or workflow step that failed.
Expected and actual result.
Relevant sync or build identifier.
A sanitized error message or screenshot.