> ## Documentation Index
> Fetch the complete documentation index at: https://beta-docs.nevermind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for Nevermined integrations

## Common Issues

Quick solutions to the most frequent problems developers encounter.

<AccordionGroup>
  <Accordion icon="key" title="Invalid API Key">
    **Error**: `Invalid API key provided`

    **Solutions**:

    * Verify your API key is correctly copied from [Nevermined App](https://app.nevermined.io)
    * Check environment variable is loaded: `console.log(process.env.NVM_API_KEY)`
    * Ensure you're using the right key for your environment (test vs production)
    * Generate a new API key if the current one expired

    ```typescript theme={null}
    // Debug API key issues
    const payments = Payments.getInstance({
      nvmApiKey: process.env.NVM_API_KEY || 'key-not-found',
      environment: 'testing',
      debug: true // Enable debug logs
    })
    ```
  </Accordion>

  <Accordion icon="wifi" title="Network Connection Issues">
    **Error**: `Network request failed` or `ECONNREFUSED`

    **Solutions**:

    * Check your internet connection
    * Verify Nevermined services are accessible
    * Try a different environment (`testing` vs `production`)
    * Check if you're behind a corporate firewall
    * Implement retry logic for transient failures

    ```typescript theme={null}
    // Test connection
    try {
      const status = await payments.getServiceStatus()
      console.log('Service status:', status)
    } catch (error) {
      console.error('Connection failed:', error)
    }
    ```
  </Accordion>

  <Accordion icon="coins" title="Insufficient Credits">
    **Error**: `Insufficient credits for redemption`

    **Solutions**:

    * Check subscriber's balance before processing
    * Verify credit consumption amount is correct
    * Ensure plan hasn't expired (for time-based plans)
    * Provide clear feedback about credit requirements

    ```typescript theme={null}
    const balance = await payments.getPlanBalance(planId, subscriberAddress)
    console.log(`Credits available: ${balance.credits}`)
    console.log(`Is subscriber: ${balance.isSubscriber}`)
    console.log(`Plan type: ${balance.planType}`)
    ```
  </Accordion>

  <Accordion icon="shield" title="Invalid Request Signature">
    **Error**: `Invalid request signature` or validation fails

    **Solutions**:

    * Ensure all required parameters are provided
    * Check signature is in the correct header: `x-nvm-query-signature`
    * Verify subscriber address matches the signer
    * Make sure plan and agent IDs are correct

    ```typescript theme={null}
    // Debug validation
    console.log('Validation params:', {
      planId,
      agentId,
      subscriberAddress,
      signature: req.headers['x-nvm-query-signature']
    })
    ```
  </Accordion>

  <Accordion icon="robot" title="Agent Not Found">
    **Error**: `Agent not found` or `404` errors

    **Solutions**:

    * Verify agent ID is correct
    * Check agent was successfully registered
    * Ensure you're using the right environment
    * Try fetching agent details directly

    ```typescript theme={null}
    try {
      const agent = await payments.getAgent(agentId)
      console.log('Agent found:', agent.metadata.name)
    } catch (error) {
      console.error('Agent lookup failed:', error)
    }
    ```
  </Accordion>

  <Accordion icon="clock" title="Plan Expired">
    **Error**: `Plan has expired` for time-based subscriptions

    **Solutions**:

    * Check plan expiration: `balance.expiresAt`
    * Remind users to renew before expiration
    * Implement grace periods if appropriate
    * Provide easy renewal options

    ```typescript theme={null}
    const balance = await payments.getPlanBalance(planId, subscriberAddress)
    if (balance.planType === 'TIME' && balance.expiresAt) {
      const expiresIn = balance.expiresAt - Date.now()
      if (expiresIn < 86400000) { // Less than 24 hours
        console.warn('Plan expires soon!')
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Debugging Techniques

### Enable Debug Logging

Get detailed logs from the SDK:

```typescript theme={null}
const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY,
  environment: 'testing',
  debug: true // Enable verbose logging
})

// Also set environment variable
process.env.DEBUG = 'nevermined:*'
```

### Test Individual Components

Break down complex operations to isolate issues:

```typescript theme={null}
async function debugWorkflow() {
  console.log('1. Testing connection...')
  try {
    const status = await payments.getServiceStatus()
    console.log('✓ Connected:', status)
  } catch (error) {
    console.error('✗ Connection failed:', error)
    return
  }

  console.log('2. Fetching agent...')
  try {
    const agent = await payments.getAgent(agentId)
    console.log('✓ Agent found:', agent.metadata.name)
  } catch (error) {
    console.error('✗ Agent not found:', error)
    return
  }

  console.log('3. Checking plan...')
  try {
    const plan = await payments.getPlan(planId)
    console.log('✓ Plan found:', plan.metadata)
  } catch (error) {
    console.error('✗ Plan not found:', error)
    return
  }

  console.log('4. Validating access...')
  try {
    const isValid = await payments.isValidRequest(
      planId, agentId, subscriberAddress, signature
    )
    console.log('✓ Access valid:', isValid)
  } catch (error) {
    console.error('✗ Validation failed:', error)
  }
}
```

### Use Testing Environment

Always test in the testing environment first:

```typescript theme={null}
// Development workflow
const environments = {
  local: 'local',
  test: 'testing',  // Base Sepolia testnet
  prod: 'production' // Base Mainnet
}

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY,
  environment: environments[process.env.NODE_ENV] || 'testing'
})
```

## Environment-Specific Issues

### Local Development

<Tabs>
  <Tab title="CORS Issues">
    **Problem**: Cross-Origin Resource Sharing errors in browser

    **Solution**:

    ```typescript theme={null}
    // Add CORS middleware
    import cors from 'cors'

    app.use(cors({
      origin: process.env.FRONTEND_URL || 'http://localhost:3000',
      credentials: true,
      allowedHeaders: ['Content-Type', 'x-nvm-query-signature']
    }))
    ```
  </Tab>

  <Tab title="SSL/HTTPS">
    **Problem**: SSL certificate errors in development

    **Solution**:

    ```typescript theme={null}
    // For local development only
    if (process.env.NODE_ENV === 'development') {
      process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'
    }

    // Or use proper local certificates
    import https from 'https'
    import fs from 'fs'

    const server = https.createServer({
      key: fs.readFileSync('localhost-key.pem'),
      cert: fs.readFileSync('localhost.pem')
    }, app)
    ```
  </Tab>

  <Tab title="Environment Variables">
    **Problem**: Environment variables not loading

    **Solution**:

    ```typescript theme={null}
    // Use dotenv for local development
    import dotenv from 'dotenv'

    // Load from specific file
    dotenv.config({ path: `.env.${process.env.NODE_ENV}` })

    // Validate required variables
    const required = ['NVM_API_KEY', 'BUILDER_ADDRESS']
    for (const key of required) {
      if (!process.env[key]) {
        throw new Error(`Missing required env var: ${key}`)
      }
    }
    ```
  </Tab>
</Tabs>

### Production Issues

<AccordionGroup>
  <Accordion icon="gauge" title="Performance Problems">
    **Symptoms**: Slow response times, timeouts

    **Solutions**:

    ```typescript theme={null}
    // 1. Implement caching
    import NodeCache from 'node-cache'
    const cache = new NodeCache({ stdTTL: 300 })

    async function getCachedAgent(agentId: string) {
      const cached = cache.get(agentId)
      if (cached) return cached
      
      const agent = await payments.getAgent(agentId)
      cache.set(agentId, agent)
      return agent
    }

    // 2. Use connection pooling
    // 3. Optimize database queries
    // 4. Implement request queuing
    ```
  </Accordion>

  <Accordion icon="chart-line" title="High Error Rates">
    **Symptoms**: Increased 5xx errors, failed validations

    **Solutions**:

    * Check service health endpoints
    * Verify API rate limits aren't exceeded
    * Review error logs for patterns
    * Implement circuit breakers
    * Scale infrastructure if needed
  </Accordion>

  <Accordion icon="dollar" title="Payment Processing Failures">
    **Symptoms**: Transactions failing, credits not updating

    **Solutions**:

    * Verify wallet has sufficient gas
    * Check token contract addresses
    * Ensure builder address is correct
    * Monitor blockchain congestion
    * Implement payment retry logic
  </Accordion>
</AccordionGroup>

## Validation Issues

### Request Validation Checklist

```typescript theme={null}
// Comprehensive validation
function validateRequest(req: Request): ValidationResult {
  const errors = []

  // 1. Check required body parameters
  const required = ['planId', 'agentId', 'subscriberAddress']
  for (const field of required) {
    if (!req.body[field]) {
      errors.push(`Missing required field: ${field}`)
    }
  }

  // 2. Check signature header
  if (!req.headers['x-nvm-query-signature']) {
    errors.push('Missing signature header: x-nvm-query-signature')
  }

  // 3. Validate address format
  const addressRegex = /^0x[a-fA-F0-9]{40}$/
  if (req.body.subscriberAddress && !addressRegex.test(req.body.subscriberAddress)) {
    errors.push('Invalid Ethereum address format')
  }

  // 4. Validate IDs format
  const idRegex = /^[a-zA-Z0-9_-]+$/
  if (req.body.planId && !idRegex.test(req.body.planId)) {
    errors.push('Invalid plan ID format')
  }

  return {
    valid: errors.length === 0,
    errors
  }
}

// Use in endpoint
app.post('/api/query', async (req, res) => {
  const validation = validateRequest(req)
  if (!validation.valid) {
    return res.status(400).json({
      error: 'Invalid request',
      details: validation.errors
    })
  }
  
  // Continue with Nevermined validation...
})
```

## Getting Help

### Debug Information Template

When seeking help, provide this information:

```typescript theme={null}
async function gatherDebugInfo() {
  const info = {
    // Environment
    nodeVersion: process.version,
    environment: process.env.NODE_ENV,
    neverminedEnv: payments.config.environment,
    
    // SDK Version
    sdkVersion: require('@nevermined-io/payments/package.json').version,
    
    // Configuration (sanitized)
    hasApiKey: !!process.env.NVM_API_KEY,
    apiKeyPrefix: process.env.NVM_API_KEY?.substring(0, 8) + '...',
    
    // Error details
    errorMessage: 'Your error message',
    errorCode: 'Error code if available',
    errorStack: 'Stack trace',
    
    // Request details
    endpoint: '/api/query',
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-nvm-query-signature': 'present'
    },
    
    // Timestamps
    timestamp: new Date().toISOString(),
    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
  }
  
  return info
}

// Save to file for sharing
const debugInfo = await gatherDebugInfo()
fs.writeFileSync('debug-info.json', JSON.stringify(debugInfo, null, 2))
```

### Support Resources

<CardGroup cols={2}>
  <Card title="Discord Community" icon="discord" href="https://discord.gg/nevermined">
    Get real-time help from developers
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/nevermined-io/payments/issues">
    Report bugs and request features
  </Card>

  <Card title="Documentation" icon="book" href="https://docs.nevermined.io">
    Comprehensive guides and API reference
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@nevermined.io">
    For critical issues and enterprise support
  </Card>
</CardGroup>

### Health Check Endpoint

Implement a comprehensive health check:

```typescript theme={null}
app.get('/health', async (req, res) => {
  const health = {
    status: 'checking',
    timestamp: new Date().toISOString(),
    checks: {}
  }

  // Check Nevermined connection
  try {
    await payments.getServiceStatus()
    health.checks.nevermined = 'ok'
  } catch (error) {
    health.checks.nevermined = 'error'
    health.status = 'unhealthy'
  }

  // Check database
  try {
    await db.ping()
    health.checks.database = 'ok'
  } catch (error) {
    health.checks.database = 'error'
    health.status = 'unhealthy'
  }

  // Check Redis cache
  try {
    await redis.ping()
    health.checks.cache = 'ok'
  } catch (error) {
    health.checks.cache = 'error'
  }

  // Overall status
  if (health.status === 'checking') {
    health.status = 'healthy'
  }

  res.status(health.status === 'healthy' ? 200 : 503).json(health)
})
```

## Prevention Tips

<Note>
  Most issues can be prevented with proper setup and testing. Follow these guidelines:

  * Always test in the testing environment first
  * Implement comprehensive error handling
  * Add monitoring and alerting
  * Keep the SDK updated
  * Follow security best practices
  * Document your integration thoroughly
</Note>

Need more help? Join our [Discord community](https://discord.gg/nevermined) where developers are ready to assist!