Troubleshooting TezLink Agent: Common Issues & Fixes

Troubleshooting TezLink Agent: Common Issues & Fixes

1. Connection failures — “Agent not reachable” or timeout

• Likely cause: Network block, incorrect RPC endpoint, or node outage.
• Fixes:
  1. Verify your internet connection and retry.
  2. Check the configured RPC endpoint URL for typos; switch to a known public Tezos node (e.g., mainnet RPC).
  3. Test the endpoint with curl or a browser:

     bash
     Copy CodeCopied
     curl -I https://<rpc-endpoint>/chains/main/blocks/head 

  4. If using a local node, ensure the node process is running and fully synced; restart if needed.

2. Authentication or permission errors

• Likely cause: Missing or invalid API keys, expired tokens, or incorrect wallet permissions.
• Fixes:
  1. Confirm any required API key or token is present and not expired.
  2. Recreate or refresh credentials via the provider or wallet.
  3. Ensure the TezLink Agent has the necessary wallet permissions (operation signing, permissions prompt accepted).
  4. Check client logs for detailed permission denial messages.

3. Transaction fails or gets rejected

• Likely cause: Low gas/fee limits, wrong counter (nonce), invalid parameters, or contract errors.
• Fixes:
  1. Increase fee and gas limits to reasonable values or enable automatic fee estimation.
  2. Fetch and apply the correct counter for the sending account.
  3. Validate all operation parameters and contract entrypoints.
  4. Simulate the operation (dry-run) against the node to see detailed revert messages.
  5. Inspect mempool and node logs for rejection reasons.

4. Transactions stuck in mempool / long confirmation times

• Likely cause: Network congestion or too-low fee.
• Fixes:
  1. Check current network fee market and bump fee if necessary.
  2. Use an operation replacement (if supported) or send a higher-fee operation with the same counter.
  3. Wait for network conditions to improve; monitor block inclusion via the RPC.

5. Key management errors (missing private key, wrong key format)

• Likely cause: Corrupt or unsupported key file, wrong derivation path, or hardware wallet issues.
• Fixes:
  1. Verify key file integrity and format (ed25519 / secp256k1 as applicable).
  2. Confirm derivation path and account index.
  3. If using a hardware wallet, ensure firmware is up to date and device unlocked; reauthorize the TezLink Agent.
  4. Restore from seed phrase only in a secure environment.

6. UI issues — agent extension or app not responding

• Likely cause: Browser extension conflicts, outdated version, or cached state corruption.
• Fixes:
  1. Reload the extension or app; clear cache and local storage for the site.
  2. Disable other browser extensions that may interfere and retry.