> ## Documentation Index
> Fetch the complete documentation index at: https://fentaris.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
fentaris init my-proxy
cd my-proxy
fentaris check --offline
```

If the project uses the legacy filename, rename it:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
mv fentaris.config.json fentaris.json
```

### Invalid Fentaris config

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "my-proxy",
  "packageManager": "pnpm",
  "entrypoint": "src/index.ts",
  "port": 4000,
  "path": "/mcp",
  "authDir": ".fentaris"
}
```

<Note>
  Allowed package managers are `pnpm`, `npm`, and `bun`.
</Note>

### `@fentaris/core` is not installed

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

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
fentaris doctor
```

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "port": 4001
}
```

### Runtime check cannot authenticate

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

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```ts theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)`.

```ts theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```ts theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```ts theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```ts theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
pnpm docs:generate
```

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

## Related Documentation

* [Quickstart](/getting-started/quickstart)
* [CLI Usage](/reference/cli)
* [Config file](/reference/config-file)
* [Environment variables](/reference/environment-variables)
* [Governance auth](/guides/governance-auth)