Error Codes Reference

Complete reference for all error codes in the GhostSpeak SDK and smart contracts, with troubleshooting steps and recovery strategies.

Error Categories

GhostSpeak errors are organized into categories for easier debugging:

Category	Code Prefix	Description
Network	`NETWORK_*`	RPC connection, timeout, rate limiting
Transaction	`TRANSACTION_*`	Transaction failures, simulation errors
Validation	`VALIDATION_*`	Input validation, data format errors
Authorization	`UNAUTHORIZED_*`	Permission denied, access control
Program	`PROGRAM_ERROR_*`	Smart contract execution errors
Account	`ACCOUNT_*`	Account not found, invalid account state
System	`UNKNOWN_*`	Unexpected errors, system failures

SDK Error Codes

Network Errors

NETWORK_ERROR

Code: NETWORK_ERRORCause: RPC connection failure, network timeout, or connectivity issues.Message: “Network connection failed”Retryable: Yes (automatic retry with exponential backoff)Troubleshooting:

Check internet connection
Verify RPC endpoint is accessible
Try alternative RPC provider (Helius, QuickNode)
Check Solana Status

Example:

try {
  const agent = await client.agents.getAgent(agentId)
} catch (error) {
  if (error.code === 'NETWORK_ERROR') {
    console.log('Retrying with backup RPC...')
    // SDK automatically retries
  }
}

TIMEOUT_ERROR

Code: TIMEOUT_ERRORCause: Operation exceeded timeout duration (default 30 seconds).Message: “Operation timed out”Retryable: YesTroubleshooting:

Increase timeout in client configuration
Use faster RPC endpoint
Reduce transaction complexity (fewer instructions)
Check network congestion

Example:

const client = new GhostSpeakClient({
  cluster: 'devnet',
  rpcConfig: {
    confirmTransactionInitialTimeout: 90000, // 90 seconds
  },
})

RATE_LIMIT_EXCEEDED

Code: RATE_LIMIT_EXCEEDEDCause: Too many requests to RPC endpoint (429 status).Message: “Rate limit exceeded. Please wait X seconds before trying again.”Retryable: Yes (after delay)Troubleshooting:

Implement request batching
Use paid RPC provider with higher limits
Enable SDK caching
Reduce request frequency

Example:

const client = new GhostSpeakClient({
  cluster: 'devnet',
  cache: { enabled: true, ttl: 60000 }, // Cache for 60s
})

Transaction Errors

TRANSACTION_ERROR

Code: TRANSACTION_ERRORCause: Generic transaction execution failure.Message: “Transaction failed to execute. Please check the details and try again.”Retryable: Sometimes (depends on cause)Troubleshooting:

Check transaction logs for specific error
Verify all accounts are correct
Ensure sufficient SOL for transaction fees
Validate instruction data format

Example:

try {
  const tx = await client.agents.register(signer, { name: 'Agent' })
} catch (error) {
  console.error('Transaction failed:', error.logs)
  console.error('Signature:', error.signature)
}

INSUFFICIENT_FUNDS

Code: INSUFFICIENT_FUNDSCause: Wallet doesn’t have enough SOL for transaction + rent.Message: “Insufficient funds to complete the transaction. Please add more funds and try again.”Retryable: No (requires funding wallet)Troubleshooting:

Check wallet balance: solana balance YOUR_ADDRESS --url devnet
Request devnet SOL from faucet
For mainnet: transfer SOL to wallet
Reduce transaction size if possible

Example:

// Check balance before transaction
const balance = await rpc.getBalance(walletAddress).send()
const requiredLamports = 5_000_000 // 0.005 SOL

if (balance < requiredLamports) {
  throw new Error(`Need ${requiredLamports} lamports, have ${balance}`)
}

SIGNATURE_VERIFICATION_FAILED

Code: TRANSACTION_ERROR (subtype)Cause: Invalid transaction signature or signer mismatch.Message: “Invalid transaction signature”Retryable: No (signature issue)Troubleshooting:

Verify correct signer is used
Check signer has authority over account
Ensure signer matches expected public key
Regenerate signature if needed

Example:

// Ensure signer matches expected authority
const agentAccount = await client.agents.getAgent(agentId)
if (agentAccount.owner !== signer.address) {
  throw new Error('Signer is not agent owner')
}

BLOCKHASH_NOT_FOUND

Code: TRANSACTION_ERROR (blockhash expired)Cause: Transaction blockhash expired (>60 seconds old).Message: “Transaction blockhash expired”Retryable: Yes (fetch new blockhash)Troubleshooting:

SDK automatically fetches fresh blockhash on retry
Reduce time between signing and sending
Use getLatestBlockhash immediately before sending

Example:

// SDK handles blockhash expiry automatically
// Manual handling:
const { blockhash } = await rpc.getLatestBlockhash().send()
// Sign and send immediately

Validation Errors

VALIDATION_ERROR

Code: VALIDATION_ERRORCause: Invalid input data or format.Message: “Invalid . ”Retryable: No (fix input)Troubleshooting:

Check field format requirements
Validate against schema
Review error message for specific field
Check SDK documentation for expected format

Example:

// Error: Invalid agent name (exceeds 64 bytes)
const tooLongName = 'A'.repeat(100)
await client.agents.register(signer, { name: tooLongName })
// Fix: Limit to 64 bytes
const validName = 'My Agent Name' // < 64 bytes

INVALID_INSTRUCTION_ERROR

Code: VALIDATION_ERROR (instruction subtype)Cause: Malformed instruction data.Message: “Invalid instruction data”Retryable: NoTroubleshooting:

Verify instruction accounts match IDL
Check data serialization format
Ensure all required fields are provided
Update SDK if using outdated version

Example:

// Missing required field
await client.agents.register(signer, {
  name: 'Agent',
  // Missing: capabilities, model
})
// Error: capabilities and model are required

Account Errors

ACCOUNT_NOT_FOUND

Code: ACCOUNT_NOT_FOUNDCause: Account doesn’t exist at the specified address.Message: “The account was not found. Please verify the address.”Retryable: No (account missing)Troubleshooting:

Verify address is correct
Ensure account was created
Check if using correct network (devnet vs mainnet)
For PDAs, verify derivation seeds are correct

Example:

// Verify agent exists before fetching
const agentAddress = await client.agents.deriveAgentAddress(owner, seed)
const exists = await client.agents.accountExists(agentAddress)

if (!exists) {
  console.log('Agent not found, creating...')
  await client.agents.register(signer, { name: 'Agent' })
}

UNAUTHORIZED_ACCESS

Code: UNAUTHORIZED_ACCESSCause: Signer doesn’t have permission for operation.Message: “Access denied. Please ensure you have the necessary permissions.”Retryable: No (permission issue)Troubleshooting:

Verify signer is account owner
Check RBAC permissions if applicable
Ensure multisig approval if required
Use correct authority signer

Example:

// Only agent owner can update agent
const agent = await client.agents.getAgent(agentId)
if (agent.owner !== signer.address) {
  throw new UnauthorizedError('Only owner can update agent')
}

Smart Contract Error Codes

DID Module Errors (6000-6009)

Code	Hex	Name	Description	Solution
6000	`0x1770`	`AlreadyDeactivated`	DID document is already deactivated	Cannot reactivate, create new DID
6001	`0x1771`	`TooManyVerificationMethods`	Maximum 10 verification methods reached	Remove unused methods before adding new
6002	`0x1772`	`TooManyServiceEndpoints`	Maximum 20 service endpoints reached	Remove unused endpoints before adding new
6003	`0x1773`	`DuplicateMethodId`	Verification method ID already exists	Use unique method IDs
6004	`0x1774`	`DuplicateServiceId`	Service endpoint ID already exists	Use unique service IDs
6005	`0x1775`	`MethodNotFound`	Verification method not found	Verify method ID exists in DID document
6006	`0x1776`	`ServiceNotFound`	Service endpoint not found	Verify service ID exists in DID document
6007	`0x1777`	`InvalidDidFormat`	DID format is invalid	Use format: `did:sol:{network}:{address}`
6008	`0x1778`	`UnauthorizedDidOperation`	Unauthorized DID operation	Use DID controller or authorized key
6009	`0x1779`	`DidDeactivated`	DID is deactivated	Cannot use deactivated DID

Common Program Errors

AlreadyDeactivated (6000)

When: Attempting to deactivate an already deactivated DID.Example Error:

Program error: custom program error: 0x1770
Error: DID document is already deactivated

Fix:

const did = await client.did.getDidDocument(agentId)
if (did.deactivated) {
  console.log('DID already deactivated')
} else {
  await client.did.deactivateDidDocument(agentId, controller)
}

TooManyVerificationMethods (6001)

When: Adding more than 10 verification methods to DID.Fix:

// Remove old methods before adding new
await client.did.removeVerificationMethod(agentId, 'old-method-id')
await client.did.addVerificationMethod(agentId, {
  id: 'new-method-id',
  type: 'Ed25519VerificationKey2020',
  publicKeyMultibase: 'z...'
})

UnauthorizedDidOperation (6008)

When: Non-controller attempts to modify DID document.Fix:

// Ensure controller signer is used
const did = await client.did.getDidDocument(agentId)
console.log('Controller:', did.controller)

// Use controller as signer
await client.did.updateDidDocument(agentId, controllerSigner, updates)

Error Handling Best Practices

Retry Logic

import { isRetryableError, getRetryDelay } from '@ghostspeak/sdk/errors'

async function retryOperation<T>(
  operation: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  let lastError: Error | null = null

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await operation()
    } catch (error) {
      lastError = error as Error

      if (!isRetryableError(lastError)) {
        throw lastError // Don't retry non-retryable errors
      }

      if (attempt < maxRetries - 1) {
        const delay = getRetryDelay(lastError, attempt)
        await new Promise(resolve => setTimeout(resolve, delay))
      }
    }
  }

  throw lastError
}

// Usage
const agent = await retryOperation(() =>
  client.agents.getAgent(agentId)
)

Error Logging

import { GhostSpeakError, logError, createErrorSummary } from '@ghostspeak/sdk/errors'

try {
  await client.agents.register(signer, { name: 'Agent' })
} catch (error) {
  if (error instanceof GhostSpeakError) {
    // Development: Full error with stack trace
    logError(error, true)

    // Production: Send to monitoring service
    const summary = createErrorSummary(error)
    await analytics.trackError(summary)

    // User-facing message
    console.error(error.userFriendlyMessage)
  } else {
    // Unexpected error
    console.error('Unexpected error:', error)
  }
}

User-Friendly Error Messages

import { formatErrorForUser } from '@ghostspeak/sdk/errors'

try {
  await performOperation()
} catch (error) {
  if (error instanceof GhostSpeakError) {
    // Show user-friendly message in UI
    toast.error(formatErrorForUser(error))
  } else {
    toast.error('An unexpected error occurred. Please try again.')
  }
}

Debugging Tools

Transaction Inspector

// Get detailed transaction logs
try {
  const tx = await client.agents.register(signer, { name: 'Agent' })
} catch (error) {
  if (error instanceof TransactionError) {
    console.log('Signature:', error.signature)
    console.log('Instruction Index:', error.instructionIndex)
    console.log('Logs:', error.logs)

    // View on explorer
    const explorerUrl = `https://solscan.io/tx/${error.signature}?cluster=devnet`
    console.log('View on Solscan:', explorerUrl)
  }
}

Account Diagnostics

import { diagnoseAccountIssue } from '@ghostspeak/sdk/utils'

const diagnosis = await diagnoseAccountIssue(rpc, agentAddress)

console.log('Account Status:', diagnosis.status)
// Output: 'not_found' | 'invalid_data' | 'rent_exempt' | 'ok'

console.log('Issues:', diagnosis.issues)
// Output: ['Account not initialized', 'Insufficient rent']

console.log('Suggestions:', diagnosis.suggestions)
// Output: ['Create account first', 'Add 0.002 SOL for rent']

Common Error Scenarios

Agent Not Found
Insufficient SOL
Rate Limited
Wrong Network

Scenario: Fetching non-existent agentError: ACCOUNT_NOT_FOUNDSolution:

const agentAddress = client.agents.deriveAgentAddress(owner, seed)
const agent = await client.agents.getAgent(agentAddress).catch(error => {
  if (error.code === 'ACCOUNT_NOT_FOUND') {
    console.log('Agent does not exist, create it first')
    return null
  }
  throw error
})

Scenario: Wallet has no SOL for transactionError: INSUFFICIENT_FUNDSSolution:

# Get devnet SOL from faucet
solana airdrop 2 YOUR_WALLET --url devnet

Scenario: Too many RPC requestsError: RATE_LIMIT_EXCEEDEDSolution:

// Use paid RPC or enable caching
const client = new GhostSpeakClient({
  cluster: 'devnet',
  rpcUrl: 'https://devnet.helius-rpc.com/?api-key=YOUR_KEY',
  cache: { enabled: true },
})

Scenario: Agent exists on devnet, fetching from mainnetError: ACCOUNT_NOT_FOUNDSolution:

// Verify cluster configuration
const client = new GhostSpeakClient({ cluster: 'devnet' })
console.log('Using network:', client.cluster) // Should match where agent was created

Support Resources

Discord Support

Get help from community and GhostSpeak team

GitHub Issues

Report bugs and request features

Troubleshooting Guide

Step-by-step debugging guide

Network Status

Check Solana network health

Quick Debug Checklist:

✅ Check network (devnet vs mainnet)
✅ Verify sufficient SOL balance
✅ Confirm RPC endpoint is accessible
✅ Validate account addresses are correct
✅ Review transaction logs on explorer

Introduction

Core Concepts

SDK Documentation

ElizaOS Plugin

CLI Documentation

Web Dashboard

Guides & Tutorials

Reference

Resources

Error Codes Reference

Error Codes Reference

Error Categories

SDK Error Codes

Network Errors

Transaction Errors

Validation Errors

Account Errors

Smart Contract Error Codes

DID Module Errors (6000-6009)

Common Program Errors

Error Handling Best Practices

Retry Logic

Error Logging

User-Friendly Error Messages

Debugging Tools

Transaction Inspector

Account Diagnostics

Common Error Scenarios

Support Resources

Discord Support

GitHub Issues

Troubleshooting Guide

Network Status

Introduction

Core Concepts

SDK Documentation

ElizaOS Plugin

CLI Documentation

Web Dashboard

Guides & Tutorials

Reference

Resources

​Error Codes Reference

​Error Categories

​SDK Error Codes

​Network Errors

​Transaction Errors

​Validation Errors

​Account Errors

​Smart Contract Error Codes

​DID Module Errors (6000-6009)

​Common Program Errors

​Error Handling Best Practices

​Retry Logic

​Error Logging

​User-Friendly Error Messages

​Debugging Tools

​Transaction Inspector

​Account Diagnostics

​Common Error Scenarios

​Support Resources

Discord Support

GitHub Issues

Troubleshooting Guide

Network Status

Error Codes Reference

Error Categories

SDK Error Codes

Network Errors

Transaction Errors

Validation Errors

Account Errors

Smart Contract Error Codes

DID Module Errors (6000-6009)

Common Program Errors

Error Handling Best Practices

Retry Logic

Error Logging

User-Friendly Error Messages

Debugging Tools

Transaction Inspector

Account Diagnostics

Common Error Scenarios

Support Resources