Troubleshooting

Common issues you may hit when running the Wallet Gateway, with fixes.

​

Database connection errors

The Wallet Gateway fails to start with database connection errors.

• PostgreSQL: verify the database exists (psql -U postgres -l), check credentials in your config, ensure PostgreSQL is running (pg_isready), and check network and firewall rules.
• SQLite: ensure the directory for the database file exists, check read/write permissions, and verify disk space.
• Memory: no configuration is needed, but remember data is lost on restart.

​

Authentication failures

API calls return 401 Unauthorized.

• Invalid or expired token: use a valid JWT, check its expiration, and regenerate it if needed.
• Missing Authorization header: include Authorization: Bearer <token> in the correct format.
• Session not found: create a session with addSession() first, ensure it has not expired, and confirm you are using the correct user context.

API calls return 503 Service Unavailable with JSON-RPC error -32002 (resource unavailable). The Wallet Gateway could not verify the token because the identity provider is unavailable; the token itself may be valid, so clients should retry instead of logging the user out. The gateway logs the underlying cause.

• IDP unreachable: check that the gateway can reach the IDP’s configUrl and the jwks_uri it advertises, and check firewall and proxy rules.
• Issuer mismatch: the issuer in the IDP’s discovery document must be identical to the issuer configured for the identity provider, including scheme, host, and trailing slash.
• Malformed responses: the discovery document and JWKS must be valid JSON. An HTML error page served with status 200 counts as unavailable.

​

Network connection issues

The Wallet Gateway cannot connect to a configured network or Ledger API.

• Network unreachable: verify the Ledger API URL, test connectivity with curl <ledger-api-url>/v2/version, and check firewall rules and routing.
• Invalid network configuration: confirm synchronizerId matches the validator, the identityProviderId matches an IDP, and the credentials are correct.
• SSL/TLS issues: verify certificates for HTTPS endpoints. In development you may need HTTP or to configure certificate trust.

​

Port already in use

EADDRINUSE: address already in use :::3030.

• Find and stop the process using the port:
  lsof -ti:3030 | xargs kill -9
  # Or inspect it first
  lsof -i :3030
  
• Use a different port:
  wallet-gateway -c ./config.json -p 8080
  
• Check whether another Wallet Gateway instance is running:
  ps aux | grep wallet-gateway
  

​

Configuration validation errors

The Wallet Gateway fails to start with configuration errors.

• Validate your config against the schema:
  wallet-gateway --config-schema > schema.json
  # Then run it through a JSON Schema validator
  
• Check for common mistakes: missing required fields, invalid JSON, type mismatches (strings vs numbers), and incorrect IDP references in networks.
• Start from the example config:
  wallet-gateway --config-example > my-config.json
  

​

Signing provider issues

Transactions fail with signing errors. Verify the provider’s configuration, environment variables and permissions:

• Fireblocks: API key and secret set in the env vars named by signingProviders.fireblocks.apiKeyEnv and secretEnv, keys valid with proper permissions, and the Fireblocks API reachable.
• Participant: the participant node is running and reachable, the party exists on it, and the participant logs show no signing errors.
• Blockdaemon: signingProviders.blockdaemon.baseUrl set, API key in the env var named by signingProviders.blockdaemon.apiKeyEnv, API reachable, and the key has signing permissions.
• DFNS: signingProviders.dfns.orgId, baseUrl, and credId set. Private key and auth token in the env vars named by privateKeyEnv and authTokenEnv. Credentials correct, and the service account has wallet-creation and signing permissions.
• Securosys: signingProviders.securosys.baseUrl set. Credentials in the env vars named by its *Env fields.
• BitGo: signingProviders.bitgo.baseUrl set, and the access token in the env var named by signingProviders.bitgo.accessTokenEnv.

See Signing providers for each provider’s setup.

​

Debugging

• Enable pretty logs for readable, detailed output:
  wallet-gateway -c ./config.json -f pretty
  
• Use structured logs for aggregation:
  wallet-gateway -c ./config.json -f json
  
• Check logs in console output, system logs, or container logs depending on how you run the Wallet Gateway.
• Verify endpoints respond:
  # Web UI
  curl http://localhost:3030
  
  # dApp API status (requires authentication)
  curl -X POST http://localhost:3030/api/v0/dapp \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{"jsonrpc":"2.0","id":1,"method":"status","params":[]}'
  

​

Getting help

If problems persist: check the logs for detailed errors, validate your configuration against the schema, review the User API and dApp API specifications, and check the project’s GitHub issues for similar reports.