Skip to main content
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. 
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. 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.

​
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 the local auth key. Provide it through FENTARIS_AUTH_KEY, --key, or the interactive prompt. 
FENTARIS_AUTH_KEY=<key> fentaris secrets set github.token --user admin

​
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. 
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.

​
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

​
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.