Troubleshooting

Common issues and how to resolve them.

Diagnose common Fentaris install, config, auth, and runtime issues

Start with the CLI checks. They catch most local setup problems before you connect an MCP client.

Quick Start

fentaris check --offline
fentaris doctor
fentaris doctor --runtime

Use check for project validation and doctor for environment diagnostics.

Project Issues

No Fentaris project found

The CLI could not find fentaris.json from the current directory upward.

fentaris init my-proxy
cd my-proxy
fentaris check --offline

If the project uses the legacy filename, rename it:

mv fentaris.config.json fentaris.json

Invalid Fentaris config

fentaris.json is missing a required field or contains an unsupported package manager.

{
  "name": "my-proxy",
  "packageManager": "pnpm",
  "entrypoint": "src/index.ts",
  "port": 4000,
  "path": "/mcp",
  "authDir": ".fentaris"
}

Allowed package managers are pnpm, npm, and bun.

@fentaris/core is not installed

fentaris doctor found @fentaris/core in package.json, but the package is missing from node_modules.

pnpm install
fentaris doctor

Use the package manager named in fentaris.json if your project does not use pnpm.

Runtime Issues

Proxy does not start

The configured port is already in use.

fentaris doctor

Change port in fentaris.json or stop the conflicting process.

{
  "port": 4001
}

Runtime check cannot authenticate

fentaris doctor --runtime reached the endpoint but did not have a valid API key.

Expected output:

error Runtime endpoint requires API-key authentication.
hint  Set FENTARIS_API_KEY or send x-fentaris-api-key from your MCP client.

export FENTARIS_API_KEY=<api-key>
fentaris doctor --runtime

Use this only for projects that enable API-key identity through the x-fentaris-api-key header.

Tools list is empty

The upstream server did not expose tools, or policy hides every tool for the current user.

Expected output when policy hides every tool:

{
  "ok": true,
  "data": {
    "tools": []
  },
  "warnings": [
    {
      "message": "No tools are visible for the selected account context."
    }
  ]
}

Check the upstream transport first:

stdio({
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "./demo-files"],
});

Then check the policy assigned to the user or group.

For an edge target, an empty list can also mean that no validated capability manifest exists yet. Complete local setup and let the deployment initialize once:

fentaris-edge status

Edge call returns EDGE_UNAVAILABLE

The selected device is offline, its connection generation changed, or the downstream session is pinned to an unavailable connection.

Expected response shape:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "EDGE_UNAVAILABLE: selected edge target is not connected"
    }
  ]
}

fentaris-edge status

Reconnect the enrolled device, then start a new downstream MCP session. Fentaris does not silently move an existing stateful session to another device.

Edge setup remains pending

The current recipe requires missing consent or a folder, file, secret, or scalar field is incomplete. A changed recipe digest requires new workload consent; a changed filesystem access level invalidates only that grant.

Run fentaris-edge status, complete the local prompt, and retry with the same desired-state version.

Edge installation requires approval

Review the exact current plan locally, then approve or deny it. A previous decision does not apply after the source, command, permissions, verification, cleanup plan, or local policy changes.

fentaris edge installation review <deployment-id> --json
fentaris edge installation approve <deployment-id> --yes --json

For custom cleanup with external side effects, repeat review and approval with --cleanup before running cleanup.

Edge installation failed or was interrupted

Inspect the bounded reason code and retryability in installation status. Retry only explicit retryable failures; the new attempt preserves the previous diagnostics.

fentaris edge installation status <deployment-id> --json
fentaris edge installation retry <deployment-id> --yes --json

source-integrity-failed, unsupported-platform, manual-prerequisite-required, approval-denied, and agent-upgrade-required need a source, device, local prerequisite, approval, or agent change rather than blind retry.

Edge installation is blocked by agent compatibility

The assignment requires protocol v3 managed installation but the connected agent negotiated an older protocol. Upgrade the Edge agent or move the assignment to a compatible device. Fentaris does not silently reinterpret the installer as a launch command.

Edge command is denied

The local executable/package allowlist rejected the recipe. Add the exact executable or package to FENTARIS_EDGE_ALLOWED_EXECUTABLES or FENTARIS_EDGE_ALLOWED_PACKAGES, reconnect the agent, and renew local consent.

Do not allow a generic shell executable to bypass the allowlist. Approve the concrete MCP executable or package.

edge__select returns EDGE_SESSION_PINNED

The logical target already has a transparent session pin. Fentaris will not move stateful work to another device. Start a new downstream MCP session, call edge__select before the first edge-dependent tool, then call the effective tool normally.

edge__call returns EDGE_INPUT_INVALID

The supplied arguments do not match the effective tool’s current input schema. Call tools/list, inspect that tool’s inputSchema, and retry. The request is rejected before any edge workload starts.

edge__call_many returns EDGE_CAPACITY

The device count, concurrency, deadline, selector candidate count, child bytes, or aggregate bytes exceeded an effective limit. Narrow the selector or lower the requested values. Client input cannot widen application limits.

Fan-out reports an indeterminate outcome

The connection was lost after a mutating child may have been dispatched. Fentaris does not retry automatically because replay could duplicate side effects. Inspect the device or upstream system, reconcile state, and retry only when the operation has an application-level idempotency contract.

Production adapter health is degraded

Run the configured Edge health checks and inspect diagnoseEdgeProductionAdapters(...). Replace reference in-memory inventory, presence, readiness, selection, binding, channel, pool-selection, and result-correlation adapters with durable multi-instance implementations before rollout.

App-Level Governance Diagnostics

Fentaris validates fluent app.policy(...) and app.group(...) declarations before serving requests. Startup or the first governed operation fails with structured configuration diagnostics when the final proxy state is invalid.

FENTARIS_CONFIG_GROUP_POLICY_UNKNOWN

A fluent group references a policy name that was not declared through app.policy(name).

app.group("guests").users(user("guest")).policy("readonly");
// Missing: app.policy("readonly").mcp("github").allow("search_issues");

Declare the named policy before attaching it to a group, or pass a concrete policy(...) instance to app.group(id).policy(...).

FENTARIS_CONFIG_GROUP_EMPTY_USERS

A fluent group has a policy but no users.

app.policy("readonly").mcp("github").allow("*");
app.group("guests").policy("readonly");
// Missing: app.group("guests").users(user("guest"))

Call app.group(id).users(user(...)) before start() or listen(...).

FENTARIS_CONFIG_GROUP_POLICY_MISSING

A fluent group has users but no policy.

app.group("guests").users(user("guest"));
// Missing: app.group("guests").policy("readonly")

Attach a named or concrete policy with app.group(id).policy(...).

FENTARIS_CONFIG_DUPLICATE_GROUP

The same group id is declared in fentaris({ groups: [...] }) and through app.group(id).

Use constructor groups or fluent groups for one id, not both. Prefer fluent declarations when modules register governance incrementally.

FENTARIS_CONFIG_DUPLICATE_POLICY

The same policy name is declared in constructor groups and through app.policy(name).

Use constructor-time policy(...) objects or app-level app.policy(name), not both for the same name.

FENTARIS_CONFIG_POLICY_SERVER_NOT_VISIBLE

A policy references an upstream MCP server that is not registered before startup.

app.policy("readonly").mcp("github").allow("*");
app.group("guests").users(user("guest")).policy("readonly");
// Missing: app.mcp("github", { transport })

Register the server with app.mcp(...) before start() or listen(...).

Auth and Secrets

Credentials cannot be decrypted

FENTARIS_AUTH_KEY is missing or does not match the local credential store.

export FENTARIS_AUTH_KEY=<key-from-env-example>
fentaris doctor

If the key is lost for a disposable local project, reinitialize the project or recreate the local credential store.

Secret command asks for a key

fentaris secrets set needs a local auth key. When the project has no encrypted credential store and no configured key, the CLI generates a random key in the project .env on the first write.

fentaris secrets set github.token --user admin

Run the command inside the project or one of its subdirectories so the CLI can discover the correct .env. An explicit --key overrides an exported FENTARIS_AUTH_KEY, which overrides the value in .env.

If credentials.enc.json already exists, Fentaris does not generate a replacement key because that would make the existing data unreadable. Restore the original key in .env or your secret manager.

Proxy fails with FENTARIS_CREDENTIALS_UNAVAILABLE

The proxy now resolves every declared default, group, user, and API-key credential before it opens its first HTTP, Edge, or custom transport. A missing environment variable, absent JSON path, unreadable file, or wrong local encryption key prevents startup. One error lists all affected references and users without exposing secret values.

Run the guided setup from the project root:

fentaris secrets setup --dry-run
fentaris secrets setup

For a deployment or CI job, provide all third-party values first and use fentaris secrets setup --non-interactive --yes --json. Fentaris generates local API keys but never invents third-party tokens. If the source uses a custom file or non-standard JSON path, follow the manual action reported by setup.

If setup created .env but an older project still reports the key as missing, make its start script load the file (node --env-file-if-exists=.env dist/index.js) or export the variables through the deployment environment. Newly generated Fentaris projects already use this form.

Auth setup requires interactive input

fentaris auth and fentaris auth api-key add without explicit values require a real terminal. In CI or other non-interactive environments, provide the user and key source:

printf '%s' "$CLIENT_API_KEY" | fentaris auth api-key add alice --value-stdin --non-interactive

Use --generate instead of --value-stdin when the job can securely capture the generated key from command output.

Secrets manifest is missing or out of date

fentaris secrets manifest --check fails when .fentaris/secrets.manifest.json does not match credential references in the project entrypoint.

Expected output:

error Secrets manifest is out of date.
hint  Run fentaris secrets manifest and commit .fentaris/secrets.manifest.json.

fentaris secrets manifest
git add .fentaris/secrets.manifest.json

Run fentaris secrets doctor to inspect missing required secrets and manifest drift before deploy or CI.

Required secret is missing locally

fentaris secrets doctor reports required credential references that are listed in the manifest but not stored in .fentaris/credentials.enc.json.

fentaris secrets set github.token --group support
fentaris secrets doctor

Set each missing reference for the reported scope. Use fentaris secrets list to review reference names and status without printing values.

Command and output playbook

These examples show the command, representative real output, the cause, and the next successful result. Secret values are intentionally omitted.

Runtime endpoint returns HTTP 401

Symptom

fentaris doctor --runtime --non-interactive

! MCP initialize  Endpoint returned HTTP 401.
  → Runtime is reachable but authentication failed. Provide
    FENTARIS_GUEST_API_KEY, FENTARIS_ADMIN_API_KEY, or FENTARIS_API_KEY.

Cause: the running proxy requires x-fentaris-api-key, but the doctor process did not receive a valid client key.

Verify and fix

FENTARIS_API_KEY="$CLIENT_API_KEY" \
  fentaris doctor --runtime --non-interactive

Expected result

✓ MCP initialize  Endpoint responded at http://127.0.0.1:4000/mcp

Policy hides and denies a tool

Symptom: tools/list for a reader omits a maintainer-only tool. Calling the hidden tool directly still fails closed:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "workspace__release_notes",
    "arguments": {}
  }
}

{
  "result": {
    "_meta": {
      "error": {
        "code": -32030,
        "message": "not-permitted",
        "policy": {
          "matchedGroups": ["readers"],
          "denialReason": "not-permitted"
        }
      }
    },
    "content": [{ "type": "text", "text": "not-permitted" }],
    "isError": true
  },
  "jsonrpc": "2.0",
  "id": 3
}

Cause: the subject’s group policy does not allow workspace.release_notes. This is expected behavior, not an upstream failure.

Verify and fix: authenticate as a subject in a policy that explicitly allows the tool, or intentionally add the permission:

policy("maintainers")
  .mcp("workspace")
  .allow("release_notes");

Expected result: the maintainer sees workspace__release_notes in tools/list, and tools/call reaches the handler.

Secrets manifest check reports drift

Symptom

fentaris secrets manifest --check --non-interactive

secrets.manifest.json is out of date. Run fentaris secrets manifest.

Cause: credential references in the entrypoint changed without updating the committed manifest.

Verify and fix

fentaris secrets manifest --non-interactive
fentaris secrets manifest --check --non-interactive
git diff -- .fentaris/secrets.manifest.json

Expected result

✓ secrets.manifest.json matches entrypoint.

Review the diff before committing. A manifest contains reference names and scopes only; it must never contain credential values.

Sensitive file is tracked by git

fentaris secrets doctor fails when encrypted credential files or other sensitive auth paths are tracked by git.

git rm --cached .fentaris/credentials.enc.json

Keep .fentaris/credentials.enc.json private. Commit only .fentaris/secrets.manifest.json.

Documentation Issues

Integrated Edge Control Plane

fentaris edge approve cannot reach the local authority

Run the command from the same project and operating-system account as the running app. Confirm edge.controlPlane.enabled is true, then run fentaris doctor --runtime. The operator endpoint descriptor and socket are created beneath the protected Edge state directory and removed during clean shutdown. Do not recreate or edit them manually.

The gateway URL is wrong or rejected

Set edge.controlPlane.publicOrigin to the externally reachable canonical origin. Use HTTPS for every non-loopback host, keep basePath distinct from the MCP path, and ensure the reverse proxy forwards WebSocket upgrades. Request Host and Forwarded headers do not override the configured origin.

A connected device has no tools

Check the device is assigned to the authenticated subject, the placement selector matches, local setup is approved, the desired and connection generations are current, and the reported manifest matches the desired recipe digest. Reconnect stale devices after fixing setup. Fentaris withholds uncertain deployments instead of publishing partial capabilities.

Managed mode fails startup

Provide all durable managed adapters, including authorization/token/enrollment services and the desired-assignment store. In-memory reference adapters are single-process and intentionally rejected for multi-instance mode. Use health and adapter diagnostics to identify the missing or unsafe contract.

Recovery and rollback

Restore the protected authority directory only from a consistent encrypted backup, then start one local instance and inspect health before allowing joins. To roll back the feature, stop assigning new Edge placements, revoke affected devices if credentials may have escaped, set edge.controlPlane.enabled to false, and restart. Do not downgrade or hand-edit stored schema records.

Generated API reference is stale

Run the docs generator after public API changes:

pnpm docs:generate

Review docs/reference-auto/ after generation. It is generated from TypeScript sources, but the surrounding handwritten reference pages may still need updates.

Related Documentation

• Quickstart
• CLI Usage
• Config file
• Environment variables
• Governance auth