Troubleshooting

Error Response Shape

Every rejected sync returns JSON like:

1{2  "ok": false,3  "error": {4    "code": "invalid_manifest",5    "message": "Sync manifest is invalid.",6    "issues": [7      {8        "code": "path_traversal",9        "message": "Docs path must not contain path traversal segments.",10        "path": "../escape.md",11        "severity": "error"12      }13    ]14  }15}

error.issues is present when there is per-file detail: manifest validation issues and warnings, route collisions, and manual edit conflicts. Entries with severity: "warning" are informational. route_collision responses also keep the routeCollisions array and manual_edit_conflict responses keep the conflicts array. Unexpected server failures return a generic message; the details are in the Payload server log.

invalid_signature

The signature does not match the canonical request string. Check the key id, private key, endpoint URL pathname, timestamp, nonce, and exact JSON body.

body_hash_mismatch

The X-VL-MD-DOCS-Body-SHA256 header does not match the request body. Sign and send the exact same body string.

nonce_replay

The nonce was already accepted for the same key id. Generate a fresh nonce by rerunning push.

oidc_invalid_token

The GitHub OIDC JWT is malformed, uses an unsupported algorithm, has an invalid signature, or cannot be verified with GitHub's current signing keys.

oidc_invalid_audience

The token audience does not match the docs set slug. Use a CLI source that matches the docs set slug. In GitHub Actions workflows, pass that source explicitly instead of relying on repository-name inference.

oidc_repository_not_allowed

The token repository is not trusted. Check GitHub OIDC records in Docs Globals > Access, especially the owner, limitRepos, and repository list.

oidc_ref_not_allowed

The token ref does not match the docs set branch.

oidc_pull_request_not_allowed

Pull request events are rejected by default. This keeps PR-originated workflows from applying docs sync unless the server explicitly opts in.

oidc_replay

The token jti was already accepted. Rerun the workflow so GitHub issues a fresh OIDC token.

source_not_allowed

The manifest source did not resolve to a docs set slug. Create a docs set with the expected slug or pass the correct --source value.

publish_disabled

The request asked to publish, but the server does not have sync.allowPublish: true.

hard_delete_disabled

The effective delete behavior is delete, but the server does not have sync.allowHardDelete: true.

route_collision

The generated docs route conflicts with another docs route or an opt-in Pages collision check. error.issues names the route and, when it comes from the manifest itself (for example guide.md and guide/index.md), the files that produce it. A route still served by a published doc of the same docs set that the sync does not publish is reported as route_retained_by_published_doc; run the change as a --publish sync.

manual_edit_conflict

A generated docs record changed outside the docs sync workflow. The sync aborts before writes to avoid overwriting human edits.

Protection covers the Markdown content (current_content_hash_mismatch) and the synced title, description, navTitle, and order (current_fields_hash_mismatch). Docs last synced before field tracking was added are checked for content only until their next successful sync. CMS-only fields such as hero images and nav overrides are never overwritten by a sync.

Docs Still Served At An Old Route

Docs set and group route changes rewrite generated docs routes immediately (see Changing Docs Set Routes). Routes that went stale before that, or a change rejected because the new routes collide with another docs set, can be fixed with repairDocsRoutes, by saving the published docs set, or with a sync.

Public /llms.txt Or Skill Route 404

If /api/llms.txt or a Payload API skill asset URL works but the public route outside /api returns HTML 404, the consuming Next app is missing the public asset route files. Run:

1pmdocs install routes --payload-app "src/app/(payload)"

Commit and deploy the generated files, then purge any cached 404 responses.

Asset Schema Missing

If an asset route or sync response says the docs assets schema is missing, the payload-markdown-docs-assets collection table has not been created yet. Run the Payload migration/dev flow against that database before syncing or serving static docs assets.

Postgres In Tests

The dev integration tests use PostgreSQL. In restricted sandboxes, Vitest may need permission to connect to the local test database.