> ## Documentation Index
> Fetch the complete documentation index at: https://gora.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common Devnet, deployment, contract metadata, mobile, and chain execution issues.

# 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:

```bash theme={null}
gora devnet status
curl http://127.0.0.1:8080/health
```

If local health works but the ngrok URL fails, check ngrok:

```bash theme={null}
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:

```bash theme={null}
gora config set node.url https://gora-dev.ngrok.app
curl https://gora-dev.ngrok.app/health
```

Or pass the node explicitly:

```bash theme={null}
gora deploy --node https://gora-dev.ngrok.app
```

If Devnet requires auth:

```bash theme={null}
gora config set api.token YOUR_TOKEN
```

## `gora validate` says the artifact is missing

Run:

```bash theme={null}
gora build
gora validate
```

Check `gora.app.json`:

```json theme={null}
{
  "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:

```bash theme={null}
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`:

```bash theme={null}
gora inspect app my_agent --node https://gora-dev.ngrok.app
```

Then invoke with the same id:

```bash theme={null}
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:

```text theme={null}
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:

```bash theme={null}
gora contract deploy --chain algorand --node https://gora-dev.ngrok.app
gora contract link --chain algorand
```

This reads:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
gora devnet status
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/contracts
```