Troubleshooting

This page consolidates common issues and solutions across the Open Privacy Suite stack.

Docker Issues

Containers not starting

# Check container status
docker-compose ps

# View logs for a specific service
docker-compose logs postgres
docker-compose logs proxy-backend
docker-compose logs anvil

# Restart a specific service
docker-compose restart proxy-backend

# Full reset (destroys volumes)
docker-compose down -v
docker-compose up -d

Container health check failing

If proxy-backend stays in "starting" state, check that its dependencies are healthy:

docker-compose logs postgres | tail -20
docker-compose logs anvil | tail -20

The backend waits for both PostgreSQL and the Ethereum node to be reachable before starting.

Docker network conflicts

If port bindings fail, check for other services using the same ports:

lsof -i :8080  # Open Privacy Suite
lsof -i :5173  # Frontend
lsof -i :5432  # PostgreSQL
lsof -i :8545  # Anvil / Ethereum node

block-explorer-frontend in restart loop: host not found in upstream "block-explorer-api"

Privacy-mode full-stack only. The block-explorer-frontend container is configured to attach to both public and bff-zone networks (docker-compose.privacy.dev.yml), but on rare daemon-state glitches docker connects only one of the two at startup. With bff-zone missing, nginx inside the container can't resolve block-explorer-api and the container crashes-and-restarts forever.

Confirm:

docker inspect privacy-proxy-block-explorer-frontend-1 \
  --format '{{range $net,$_ := .NetworkSettings.Networks}}{{$net}} {{end}}'
# Expected:  privacy-proxy_bff-zone privacy-proxy_public
# Broken:    privacy-proxy_public                          ← only one

Fix — force-recreate just the frontend (no data loss, the explorer postgres stays up):

set -a && source .env.privacy.dev && set +a
docker compose -f docker-compose.privacy.dev.yml \
  up -d --force-recreate --no-deps block-explorer-frontend

If the issue recurs on every make full-stack-dev, file a ticket — durable causes can include compose-version differences or a stale network entry left behind by a previous compose project. The compose config on main is correct; the symptom is daemon-side state, not config.

Database Issues

Cannot connect to PostgreSQL

# Check if PostgreSQL container is running
docker-compose ps postgres

# Connect manually
docker-compose exec postgres psql -U postgres -d privacy_proxy

# Check connection string
echo $DATABASE_URL

Migration failures

# View migration status
docker-compose logs proxy-backend | grep -i migrat

# Reset database completely (destroys all data)
docker-compose down -v
docker-compose up -d

testcontainers failures in unit tests

If unit tests fail to start PostgreSQL via testcontainers:

1. Verify Docker is running: docker info
2. Check Docker socket permissions
3. Set TEST_DATABASE_URL to use an external PostgreSQL instead:

export TEST_DATABASE_URL="postgres://postgres:postgres@localhost:5432/privacy_proxy_test?sslmode=disable"
go test ./internal/...

Authentication Issues

Token expiration

Access tokens expire after 5 minutes (production; dev/mockauth builds use 30 minutes). Refresh tokens expire after 7 days.

# Refresh an expired access token
curl -X POST http://localhost:8080/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

If the refresh token is also expired, re-authenticate through the web UI.

Azure AD authentication failures

RBAC Issues

Claims hierarchy

Remember that the admin claim has implied permissions:

• admin implies deploy and upgrade

The legacy read / write claims were removed — non-privileged method access is now gated solely by the per-group method allowlist (GroupAccess.allowed_methods). Don't try to add read or write as claims; the resolver no longer recognizes them.

Blocked methods

The following method families are always blocked regardless of permissions:

debug_*    admin_*    personal_*    miner_*
txpool_*   clique_*   les_*         eth_sign
eth_signTransaction   eth_subscribe  eth_unsubscribe

The exception is debug_traceCall and debug_traceTransaction: they are allowed when listed in the group's allowed methods, and are then checked as described in RBAC.

Multicall blocked

Calls to known Multicall contract addresses are blocked because they allow batching arbitrary contract calls, bypassing method-level restrictions:

• Multicall3: 0xcA11bde05977b3631167028862bE2a173976CA11
• Multicall2: 0x5ba1e12693dc8f9c48aad8770482f4739beed696
• Multicall1: 0xeefba1e63905ef1d7acba5a8513c70307c1ce441

Port Conflicts

Build Issues

Go build failures

# Clean module cache
go clean -modcache

# Re-download dependencies
go mod download

# Verify dependencies
go mod verify

Frontend build failures

cd frontend

# Clear node_modules and reinstall
rm -rf node_modules
npm install

# Clear Vite cache
rm -rf node_modules/.vite
npm run dev

Docker build failures

# Rebuild without cache
docker-compose build --no-cache

# Pull latest base images
docker-compose pull

Rate Limiting

If you are receiving 429 Too Many Requests:

• Determine whether the response is a local concurrency rejection, a signed-approval simulation budget rejection, or an upstream rate-limit/circuit-breaker rejection by checking proxy metrics and logs.
• For a local concurrency rejection, reduce simultaneous in-flight requests and retry after existing requests finish.
• For rate limit exceeded (requests per second) on eth_sendRawTransaction with signed approvals enabled, the identity used up its simulation budget: spread submissions out, or raise OPS_APPROVAL_PREFLIGHT_RATE / OPS_APPROVAL_PREFLIGHT_BURST if the workload legitimately needs more.
• For an upstream rejection, check the rate tier associated with the group's rpc_api_key (or the global fallback key) in the upstream RPC proxy.
• Respect Retry-After when present. Changing group permissions inside Open Privacy Suite does not change the upstream API key's quota.

Getting Help

If your issue is not covered here:

1. Check the backend logs: docker-compose logs -f proxy-backend
2. Run tests with verbose output: go test -v ./e2e/...
3. Check the GitHub Issues for known problems.