Troubleshooting

What to do when ascribe won’t install or start, a check in CI compared nothing, ascribe diff finds no merge base, the Astro build or astro dev fails, or an agent doesn’t hear from Ascribe.

The problems you can meet installing Ascribe, checking in CI, building with Astro, and setting up an agent, by what you see. Each entry gives the text you see, its cause, and the fix. For a problem with review, see Troubleshooting review.

ascribe can’t find its native package

npx ascribe or pnpm exec ascribe stops with:

@ascribed/cli could not find its native package @ascribed/cli-linux-x64 (…). Reinstall @ascribed/cli for linux/x64, and ensure optional dependencies are enabled. The package manager must not omit optional dependencies.

Cause. @ascribed/cli installs the binary for your platform as an optional dependency, and your package manager left it out. That happens with --no-optional or --omit=optional, with optional=false in .npmrc, or with a lockfile written on another platform. It also happens on a platform Ascribe has no binary for (Platforms).

Solution.

ascribe won’t start on Linux: GLIBC not found

On Linux, ascribe stops before it runs, with a message that a version of GLIBC_ wasn’t found.

Cause. Ascribe’s Linux binaries need glibc 2.28 or later, and the system is older. A distribution built on musl, such as Alpine, has no glibc at all.

Solution. Run ascribe on a system with glibc 2.28 or later. In CI or a container, use a newer image, such as a current Debian or Ubuntu one. The build images of Netlify, Vercel, Cloudflare Pages, and AWS Amplify all have it (Platforms).

ASC257 in CI: the addresses weren’t compared

ascribe check in CI warns at ascribe.addresses, and --deny-warnings fails the job:

the addresses weren't compared with the base: …

Cause. ascribe check compares the addresses the docs publish with the base’s, and it couldn’t read the base. The checkout has no history, as actions/checkout gives by default, or the base isn’t there, as after a force-push (addresses-base-unreadable).

Solution.

Keep the addresses you’ve published has the workflow.

ascribe diff: no merge base

ascribe diff exits with 2 and one of these:

error: this clone doesn't have enough history to find where the branch left `main`: fetch more of it (in GitHub Actions, `fetch-depth: 0` on actions/checkout), or pass --base-exact to compare with `main` itself
error: `main` and HEAD share no history, so there's no merge base to compare with; pass --base-exact to compare with `main` itself

Cause. ascribe diff compares with the point where your branch left the base, its merge base. A shallow clone doesn’t have that commit, and two unrelated histories have none (Exit codes).

Solution. Do what the message says:

• A shallow clone: fetch the history. In GitHub Actions, give actions/checkout fetch-depth: 0.
• No shared history: pass --base-exact, to compare with the base itself.

ascribe drift stops the same way, and its messages leave out --base-exact, which it doesn’t have. Fetch the history, or pass a --base that shares history with HEAD.

astro build: site doesn’t match

astro build or astro dev stops with:

@ascribed/astro: ascribe.toml and astro.config disagree:
- [consumer] site is "https://example.com", but Astro's `site` is "https://docs.example.com".

The list can name base-path, trailing-slash, or Astro’s build.format too.

Cause. Ascribe writes every link with [consumer]’s settings in ascribe.toml. A site whose routes differ would have broken links, so the build fails (What the integration does).

Solution. Write each setting once, in [consumer]:

astro dev answers 503

Every page in astro dev says:

Ascribe build failed; fix the source and save to retry.

Cause. The last rebuild failed. Until a save builds cleanly again, pages answer with HTTP 503, so you never see a stale page (In astro dev).

Solution.

The host doesn’t list Ascribe’s MCP tools

Your agent’s host lists no ascribe_ tools, or says the ascribe server failed to start.

Cause. The host couldn’t start ascribe mcp. Usually:

• The host hasn’t read the new entry: it reads its servers when a session starts.
• ascribe isn’t on the host’s path. The entry sync writes runs the ascribe on the path.
• With npx --no-install, @ascribed/cli isn’t in the package.json of the folder the host starts in, or of a folder above it.
• The host asks you to approve a project’s servers, and you haven’t.

Solution.

Set up the MCP server has the entries for each host.

The hook says nothing

The agent writes a page with an error, and never hears about it.

Cause. The hook reports some things and not others (What the agent hears). It says nothing:

• When the file isn’t a page or a fragment of a project.
• About warnings, or advice that has no safe fix.
• When the check takes longer than 2 seconds after an edit, or 20 before the agent finishes: it’s given up.
• Before the agent finishes, about changes the agent already committed, or when the agent is already continuing because of a stop hook.
• When no entry runs it: the project has no entries, or, in Codex, you haven’t trusted the project’s hooks.

Solution.

For more information

• Install: the platforms, and every way to install ascribe.
• Checks in CI: the workflow, and why it fetches the history.
• ascribe diff: what it compares.
• The Astro integration: its options, and what it checks.
• Set up the MCP server and Check an agent’s edits with hooks: Ascribe for agents.
• Troubleshooting review: the page preview, the site preview, and the HTML preview.