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 reconnect the agent. The agent starts a bounded capability probe during reconciliation and publishes the manifest before reporting the deployment ready:

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

When fentaris edge status --json reports reasonCategory as executable-policy-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, then reconnect the agent.

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.

Project vault is locked

macOS uses Keychain; servers/CI and unsupported systems require an explicit FENTARIS_VAULT_KEY or an application credential-store adapter. Fentaris never generates the key into .env and never regenerates one over existing encrypted data. Restore the original unlock mechanism. Wrong or missing keys preserve the vault and report a locked state.

fentaris secrets check --offline --json

Run inside the project so discovery selects the correct root. Defined process environment values take precedence over automatically loaded project .env. Legacy credentials.enc.json requires its original FENTARIS_AUTH_KEY; preserve both during explicit migration. See project vault recovery.

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.

Core and CLI load project .env automatically before configuration evaluation; defined process values win. Restore the explicit legacy key for old scoped stores, or migrate sources to the project vault before using the new secrets commands.

Auth setup requires missing input

fentaris auth displays incoming identities. auth keys requires an explicit action. In a terminal, create asks only for missing user/name fields; JSON/noninteractive/non-TTY execution returns missing fields without waiting.

fentaris auth keys create --user alice --name workstation --non-interactive --json

This creation result deliberately includes a sensitive generated key once. Securely capture it; inventory and revoke never include the value. Revoke an undisplayed key by its ID if write verification failed. Configure projectVaultIdentityStrategy for runtime enforcement.

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