Troubleshooting

Container Fails to Start

If the container fails on startup with a mount error, make sure this exists on your host:

mkdir -p ~/.config/opensana

Environment Variables Missing in the Container

Host environment variables must be exported before the container starts.

If they are missing:

1. update your shell profile
2. open a new terminal or reload the shell
3. rebuild or reopen the container

MCP Cannot Reach OpenSana

In strict mode, the firewall may be blocking the required domain.

Check that the OpenSana deployment host is included in the firewall allowlist and rebuild or re-run the firewall script if needed.

Claude Code Cannot Reach Bedrock

Verify:

• AWS_BEARER_TOKEN_BEDROCK is set
• AWS_REGION is correct
• the selected network mode matches your expectation
• the container was rebuilt after any firewall or environment change

Intermittent Retry Failures

If AI requests start failing with retries and no clear HTTP status, the most likely cause is stale firewall allowlist data in strict mode.

Usually the fix is:

sudo /usr/local/bin/init-firewall.sh

or a full container restart.

When To Switch to Open Mode

If you want to confirm whether the firewall is the problem, temporarily switch to:

export DEVCONTAINER_NETWORK_MODE=open

If the issue disappears in open mode, the firewall configuration is the likely cause.