Troubleshoot the CLI, Git sync and MCP

Use this page when a dxb command fails, a Git push does not reach your docs, or an AI agent cannot connect to the Doxbrix MCP server. Each entry names the symptom as you see it, explains the cause, and gives a check, a fix, and a way to confirm recovery. Start with the least invasive check.

Read the exit code first

Every dxb command exits with a stable code, so scripts and CI jobs can branch on the kind of failure. Add --verbose (-v) to print request IDs and stack traces, and --json to get machine-readable output on stdout.

To check your setup in one step, run:

dxb doctor

dxb doctor checks the API URL, authentication, the selected project, the folder link, and docs.json lint.

CLI

“You are not logged in.” or “Authentication failed.” (exit 3)

Cause. The CLI has no token, or the API rejected it because it is invalid, expired, or revoked. The CLI reads a token from --token, then the DOXBRIX_TOKEN environment variable, then the saved profile.

Check. Run dxb whoami. In CI, confirm that DOXBRIX_TOKEN is set and not empty.

Fix. On your computer, run dxb login. In CI, create a new token and update the secret. See Create and revoke access tokens.

Confirm. dxb whoami prints your account email.

“This token is missing the '…' scope.” (exit 3)

Cause. The token works but lacks the scope the command needs. For example, dxb push needs docs:write, and connecting Git needs project:admin. The CLI reports this as an authentication error, not a plan problem.

Fix. Run dxb login again to get a token with the scopes the CLI needs, or create a token with the right scopes. The scope table is in the REST API reference.

Confirm. Rerun the command. It no longer exits with code 3.

“No project selected.” (exit 2)

Cause. A project command ran without a project reference.

Fix. Use one of these:

dxb git status --project pocketbase-docs   # pass the project each time
export DOXBRIX_PROJECT=pocketbase-docs      # set it for the shell or CI job
dxb project use pocketbase-docs             # remember it in a linked folder

Confirm. dxb status shows the project.

“Not inside a Doxbrix docs project.” (exit 2)

Cause. You ran a local command such as dxb lint, dxb new, dxb dev, or dxb pull outside a folder that contains docs.json.

Fix. cd into your docs folder, pass --cwd <dir>, or run dxb init to create a project. To attach an existing folder to a cloud project, run dxb link pocketbase-docs, or dxb link --create to create a new cloud project. If dxb link prints Specify a project to attach, or use --create., add one of those arguments.

Confirm. dxb status runs without the error.

“Lint failed.” or “Refusing to push: N lint error(s).” (exit 2)

Cause. docs.json or a page has lint errors. dxb push checks lint before it uploads and refuses to push while any error remains. Warnings do not block a push.

Check. Run dxb lint to list each error with its rule name.

Fix. Correct each reported error, then run dxb lint again. For the file format, see docs.json and page format reference.

Confirm. dxb lint exits 0 and dxb push proceeds.

“Refusing to push: N file(s) are not in docs.json.” (exit 2)

Cause. With --strict, the push fails when page files exist on disk but are not listed in docs.json. Without --strict, the CLI warns that those files will not be published.

Fix. Run dxb sync to add the files to docs.json, or create pages with dxb new page. Pass --allow-orphans only when you intend to leave the files unpublished.

Confirm. dxb push --strict completes without the error.

A CI job succeeds but nothing is published

Cause. The job log shows Aborted. When the CLI does not run in a terminal, every confirmation takes its default answer, which is no. The command stops and exits with code 0.

Fix. Pass --yes (-y) to answer prompts in advance:

dxb push --publish --yes --strict

Confirm. The job log shows the pushed pages, and the change appears on the reader site. For a complete pipeline, see Run dxb checks and pushes in CI.

“Your plan does not include this feature.” (exit 4)

Cause. The API returned 402 or 403 because the workspace plan does not include the feature, such as Git sync, or a plan limit was reached. The hint says Upgrade to Pro or Business to use this.

Fix. Ask a workspace owner to compare plans in Plans and limits reference and upgrade in Manage billing and change plans.

Confirm. Rerun the command after the plan change.

“Rate limited. Retry in Ns.” or a network error (exit 6)

Cause. Too many requests in a short time, or the CLI cannot reach the API. Network errors include the hint Check your connection and DOXBRIX_API_URL.

Fix. For a rate limit, wait the number of seconds shown, then retry. For a network error, check your connection, proxy, and the API URL. Run dxb config get api-url or check DOXBRIX_API_URL; the value must be an HTTPS origin such as https://app.doxbrix.com.

Confirm. dxb doctor reports that the API is reachable.

Git sync

Commits pushed to the repository do not appear in Doxbrix

Cause. Doxbrix updates pages when your Git provider sends a push webhook to the Webhook URL shown in Git Sync. If the webhook is missing, rejected, or sent for a different branch, nothing is synced until the next manual or scheduled sync. The app does not show how to set a webhook secret.

Check. In your repository's webhook settings, open recent deliveries for the Doxbrix webhook and read the response:

Fix. In Git Sync, select Sync now to pull the latest commits immediately. With the CLI, run dxb git sync. Make sure you push to the tracked branch shown on the repository card. If signature errors continue, rely on Sync now or scheduled reconciliation until the webhook is corrected.

Confirm. The run history shows a new run with status Success or Partial, and the page shows the change.

A sync run shows Partial

Cause. At least one page was edited in both Doxbrix and Git in the same place. Doxbrix applied the conflict policy and kept both versions for review.

Fix. Review each conflict and keep the editor or Git version. See Resolve Git sync conflicts.

Confirm. dxb git conflicts list prints No conflicts.

Connecting a repository fails with git_sync_unavailable

Cause. The API returned 402 because Git sync is not available for the project, usually because of the workspace plan.

Fix. Check the plan in Plans and limits reference. To connect after upgrading, follow Sync a project with a Git repository.

Confirm. Git Sync shows the repository with the status Connected.

Pushes to a hosted existing site do not trigger a build

Cause. For a project that hosts an existing docs site, a push rebuilds the site only when auto-deploy by webhook is turned on. Otherwise the webhook response says auto-deploy by webhook is not enabled for this project.

Fix. Turn on webhook auto-deploy, or deploy manually. See Manage deployments, auto-deploy and rollback.

MCP server

“Unauthorized: provide a dxb_ Personal Access Token via Authorization: Bearer.”

Cause. The client's first request did not include a token.

Fix. Add the header Authorization: Bearer ${DOXBRIX_TOKEN} to the server entry, and set DOXBRIX_TOKEN in the environment the client starts from. Restart the client.

Confirm. The client shows the doxbrix server as connected and list_projects returns your projects.

“Not found. MCP endpoint is POST /mcp.”

Cause. The client URL does not end in /mcp, for example https://mcp.doxbrix.io/ or /sse.

Fix. Use the full endpoint URL, such as https://mcp.doxbrix.io/mcp?project=acme-docs. The server supports only the Streamable HTTP transport, so a stdio command configuration does not work.

Confirm. curl <host>/health returns "ok": true, and the client connects.

“Missing or unknown Mcp-Session-Id (initialize first).” or “No valid session”

Cause. The client sent a request for a session the server does not know, for example after the server restarted, or its first request was not initialize.

Fix. Restart or reconnect the MCP client so it starts a new session.

Confirm. Tool calls succeed after the reconnect.

The agent cannot create or edit pages

Cause. The session is in local mode, which is the default. Write tools such as create_page and update_page are not offered.

Fix. Keep local mode and push the agent's files with dxb push, or add mode=cloud to the URL if the agent must edit the live project. See Connect AI agents with the MCP server.

“Publishing is disabled on this MCP connection (DOXBRIX_ALLOW_PUBLISH is off).”

Cause. The server does not allow publish_page. The page stays a draft.

Fix. Publish the page in the editor, or ask the server operator to set DOXBRIX_ALLOW_PUBLISH=1. Even then, pages in projects that require approval are submitted for review instead of published.

Get more help

When you contact support, include the command, the exit code, and the request ID. Run the command again with --verbose to print the request ID.