Skip to main content

​
Troubleshooting

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

​
Devnet health returns 404 or fails

On the VM, check that the Gora dev API is running: 
gora devnet status
curl http://127.0.0.1:8080/health
If local health works but the ngrok URL fails, check ngrok: 
curl https://gora-dev.ngrok.app/health
Common causes:
  • gora devnet up is not running
  • ngrok is not authenticated
  • the reserved ngrok domain is already in use
  • the tunnel points at the wrong local port
  • another process was already using port 8080

​
Local CLI cannot reach Devnet

From your app folder: 
gora config set node.url https://gora-dev.ngrok.app
curl https://gora-dev.ngrok.app/health
Or pass the node explicitly: 
gora deploy --node https://gora-dev.ngrok.app
If Devnet 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-dev.ngrok.app/health
gora build
gora validate
gora package
gora deploy --node https://gora-dev.ngrok.app
If the endpoint is healthy but deploy still fails, check whether the node requires a bearer token.

​
gora invoke says the app does not exist

Confirm the app id in gora.app.json: 
gora inspect app my_agent --node https://gora-dev.ngrok.app
Then invoke with the same id: 
gora invoke --app my_agent --input fixtures/request.json --wait
Remember: app names with hyphens become app ids with underscores. my-agent becomes my_agent.

​
JS/TS/Python runs locally but fails on Devnet

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-dev.ngrok.app
gora contract link --chain algorand
This reads: 
curl https://gora-dev.ngrok.app/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. The Devnet 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

This is expected if you only invoked the Gora app. gora invoke runs your off-chain app and returns a result or intent. It does not automatically submit a Base, Solana, or Algorand transaction. To make chain state change, connect one of:
  • mobile signing request
  • gateway fulfillment
  • app contract callback
  • smart wallet execution
  • chain-specific submitter

​
Mobile shows no pending request

Check:
  • the app was invoked successfully
  • the app returned mobile_signing_request or an approval-compatible result
  • the dev 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-dev.ngrok.app
gora contract deploy --chain <chain> --node https://gora-dev.ngrok.app
gora contract link --chain <chain>
gora build
gora validate
gora deploy
gora invoke --app <app_id> --input fixtures/request.json --wait
For a Devnet operator: 
gora devnet status
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/contracts