Troubleshooting

Fix common testnet, local devnet, deployment, contract metadata, mobile, and chain execution issues.

Troubleshooting

Start with the symptom, then run the checks in order.

Cannot reach the live testnet

Check the live endpoint (full endpoint list: Connect to the testnet):

curl https://gora-bridge.74.241.248.103.nip.io/health
curl https://gora-bridge.74.241.248.103.nip.io/v1/apps

/health returns the bridge route list. /v1/apps answers from the node API — one hostname serves both roles, with node routes under /v1/*.

If you are running your own local devnet instead of the live testnet, use the local devnet checks at the bottom of this page.

Local CLI cannot reach the node

From your app folder:

gora config set node.url https://gora-bridge.74.241.248.103.nip.io
curl https://gora-bridge.74.241.248.103.nip.io/v1/apps

Or pass the node explicitly:

gora deploy --node https://gora-bridge.74.241.248.103.nip.io

If the node requires auth:

gora config set api.token YOUR_TOKEN

gora validate says the artifact is missing

Run:

gora build
gora validate

Check gora.app.json:

{
  "artifact": {
    "kind": "typescript",
    "path": "src/index.ts"
  }
}

Make sure the file exists and is not empty.

gora validate says there is a secret

Remove private or credential-like values from source, manifest, policy, fixtures, and package metadata.

Do not package:

• private keys
• mnemonics
• deployer keys
• API tokens
• RPC secrets
• Algod tokens

Use environment variables or local dev-only wallet import instead.

gora deploy fails

Check:

curl https://gora-bridge.74.241.248.103.nip.io/health
gora build
gora validate
gora package
gora deploy --node https://gora-bridge.74.241.248.103.nip.io

If the endpoint is healthy but deploy still fails, check whether the node requires a bearer token.

Two errors mean the app id is already registered on the shared testnet:

• upgrade must publish a new version label — it’s your app: bump version_label in gora.app.json and redeploy.
• only the current owner may publish an upgrade — someone else picked that name first (app ids are global). Rename your app (app_id in gora.app.json, or gora init a fresh directory with a unique name).

gora invoke says the app does not exist

Confirm the app id in gora.app.json:

gora inspect app my_agent --node https://gora-bridge.74.241.248.103.nip.io

Then invoke with the same id:

gora invoke --app my_agent --input fixtures/request.json

Remember: app names with hyphens become app ids with underscores. my-agent becomes my_agent.

JS/TS/Python runs locally but fails on the node

Check the runtime contract:

stdin:  JSON request envelope
stdout: JSON result only
stderr: logs
exit 0: success
exit nonzero: failure

Common issues:

• logs printed to stdout
• invalid JSON output
• app reads a local file that was not packaged
• app depends on unavailable network access
• manifest artifact path points to the wrong file

Algorand deploy asks for --datadir

Use --datadir only on the VM running the Algorand localnet.

From a local computer, do this instead:

gora contract deploy --chain algorand --node https://gora-bridge.74.241.248.103.nip.io
gora contract link --chain algorand

This reads:

curl https://gora-bridge.74.241.248.103.nip.io/v1/contracts/algorand

and records the returned app_id locally.

Contract metadata says needs_deployment

The Gora node knows the chain but not a deployed gateway/contract yet.

On the live public testnet this is expected for the separate Base and Solana Gora gateways, not every chain capability. Validator staking is deployed on all three chains. Base/Solana apps can write to their own contracts/programs using separately approved managed agent signers without a Gora gateway. See Connect to the testnet and the Base/Solana app guide.

On a local devnet, the operator should deploy or configure it on the VM, then update the registry. Depending on chain, set or produce:

• Base: BASE_CONTRACT_ADDRESS
• Solana: SOLANA_PROGRAM_ID
• Algorand: ALGORAND_APP_ID

Then restart or refresh Devnet metadata.

No chain transaction happened after invoke

An ordinary invocation can return data without requesting any chain write. Invocation success alone does not establish transaction confirmation. A managed app can propose a policy-authorized callback; check its settlement separately with GET /v1/settlements/{request_id} using the same caller authentication. Require confirmed and independently inspect the transaction/contract state.

To make chain state change, configure the appropriate path:

• mobile signing request
• gateway fulfillment
• app contract callback
• smart wallet execution
• chain-specific submitter
• managed Base/Solana agent signer with an explicit bounded policy

Mobile shows no pending request

Check:

• the app was invoked successfully
• the app returned mobile_signing_request or an approval-compatible result
• (local devnet only) the node has a signing-request sink configured
• mobile points at the correct bridge/inbox
• you are looking at the correct app id

Mobile signed, but the contract did nothing

A signature alone is not enough. The signed response must be submitted to the chain or gateway.

Check:

• submission_plan exists
• chain RPC is reachable
• gateway or contract address is correct
• contract rejects duplicate request ids
• contract accepts the proof/attestation format used by Devnet
• sender has enough dev funds

Which command should I run next?

For a local developer:

gora contract doctor --chain <chain> --node https://gora-bridge.74.241.248.103.nip.io
gora contract deploy --chain <chain> --node https://gora-bridge.74.241.248.103.nip.io
gora contract link --chain <chain>
gora build
gora validate
gora deploy
gora invoke --app <app_id> --input fixtures/request.json

For a local devnet operator, use the checks below.

Local devnet checks

Everything in this section applies only when you run your own local devnet with gora devnet up — none of it is needed against the live testnet.

On the VM, check that the Gora dev API is running:

gora devnet status
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/contracts

If local health works but your public tunnel URL fails, check the tunnel (ngrok, Caddy, or any HTTPS tunnel works):

curl https://YOUR-PUBLIC-URL/health

Common causes:

• gora devnet up is not running
• the tunnel is not authenticated or not running
• the reserved tunnel domain is already in use
• the tunnel points at the wrong local port
• another process was already using port 8080