Troubleshooting

A provider model is missing

1. Verify the provider base URL and credentials.
2. Refresh the provider's model list.
3. If discovery is unsupported, add the exact model ID from the provider documentation.
4. Check for account, billing, region, or API-access restrictions at the provider.

A conversation cannot continue after upgrading

An earlier conversation may reference a retired local model. Its history remains readable, but Biyan will not silently replace that model or start a paid request. Select a configured remote provider/model before sending the next message.

A document cannot be sent

• Confirm the file is at most 20 MB.
• For scanned/image-only PDFs, use a provider that supports the file natively; local OCR is not provided.
• If extracted text plus conversation context exceeds the model/provider budget, shorten the source outside Biyan or choose a provider with a sufficient limit.
• Biyan does not silently truncate or summarize the file.

Migration recovery screen

Choose Retry after resolving disk-space, permissions, or lock problems. Do not delete the legacy source or staging directory while migration is active. The migration step advances only after validation and atomic activation succeed.

If several earlier data folders are detected, verify the selected source shown by Biyan. Sources are not merged automatically.

API gateway errors

• 401: verify the local gateway key, not the upstream provider key.
• 410 LOCAL_RUNTIME_REMOVED: select a configured remote model; the requested model belongs to a retired local runtime.
• 502: inspect the selected provider's endpoint, account status, and redacted response.
• Connection refused: start the API gateway and verify its host and port.

MCP server does not start

Verify the command exists, arguments are separated correctly, and required environment variables are present. Grant only necessary tools and restart the server. The built-in migration renames the managed integration to Biyan Web Research; conflicting user-created entries remain disabled for review.

Get safe diagnostics

Record:

• Biyan version and data schema;
• operating system and architecture;
• the action that failed;
• a short redacted error code/message.

Email help@biyan.ai if the problem continues.