Troubleshooting Guide

This guide covers common issues you might encounter while using PromptCompose and provides step-by-step solutions.

Platform Issues

Account and Authentication

Cannot Login to Platform

Symptoms:

• Login page shows “Invalid credentials”
• Social login (Google/Microsoft) fails
• Email verification not working

Solutions:

1. Check Credentials

   • Verify email address is correct
   • Check if Caps Lock is on for password
   • Try password reset if uncertain

2. Social Login Issues

   • Clear browser cookies and cache
   • Try incognito/private mode
   • Disable browser extensions temporarily
   • Ensure third-party cookies are enabled

3. Email Verification Problems

   • Check spam/junk folder for verification emails
   • Wait 5-10 minutes for email delivery
   • Request new verification code
   • Contact support if emails aren’t received

Session Expires Frequently

Symptoms:

• Logged out after short periods of inactivity
• “Session expired” messages appear often

Solutions:

1. Browser Settings

   • Enable cookies for PromptCompose domain
   • Clear browser cache and cookies
   • Update browser to latest version

2. Security Settings

   • Check if company firewall is interfering
   • Disable VPN temporarily to test
   • Whitelist PromptCompose domains

Dashboard and Navigation

Dashboard Not Loading

Symptoms:

• Blank dashboard screen
• Loading spinner indefinitely
• “Failed to load resources” error

Solutions:

1. Browser Troubleshooting

   • Hard refresh: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
   • Clear browser cache and cookies
   • Try different browser or incognito mode

2. Network Issues

   • Check internet connection
   • Disable VPN or proxy temporarily
   • Check if firewall is blocking requests

3. Browser Extensions

   • Disable ad blockers temporarily
   • Turn off privacy extensions
   • Test with all extensions disabled

Sidebar Navigation Not Working

Symptoms:

• Clicking sidebar items doesn’t navigate
• Sidebar appears collapsed or missing
• Menu items not responsive

Solutions:

1. Responsive Design Issues

   • Check if browser window is too narrow
   • Try full-screen mode
   • Test on different screen resolutions

2. JavaScript Errors

   • Open browser developer tools (F12)
   • Check console for JavaScript errors
   • Report specific error messages to support

Prompt Management

Cannot Create or Edit Prompts

Symptoms:

• “Create Prompt” button not working
• Monaco Editor not loading
• Save operation fails

Solutions:

1. Editor Loading Issues

   • Wait for editor to fully load (may take 10-15 seconds)
   • Refresh page if editor doesn’t appear
   • Check browser console for errors

2. Permission Problems

   • Verify you have Editor or Owner permissions
   • Check with project admin about access levels
   • Ensure project is active and not archived

3. Browser Compatibility

   • Use supported browsers: Chrome, Firefox, Safari, Edge (latest versions)
   • Enable JavaScript in browser settings
   • Clear browser cache

Variable Interpolation Not Working

Symptoms:

• Variables showing as {{variable_name}} in resolved content
• “Missing variable” errors
• Variables not being replaced with values

Solutions:

1. Variable Definition Issues

   • Check variable names match exactly (case-sensitive)
   • Ensure variables are defined in the prompt
   • Verify variable types match provided values

2. Syntax Problems

   • Use correct syntax: {{variable_name}}
   • No spaces inside brackets: {{ variable }} is incorrect
   • Check for typos in variable names

3. API Integration Issues

   • Verify variables are passed correctly in API calls
   • Check SDK variable parameter format
   • Review API documentation for proper syntax

A/B Testing

A/B Tests Not Running

Symptoms:

• Test status shows “Active” but not serving variants
• All users getting same variant
• “No active tests” message despite creating tests

Solutions:

1. Test Configuration

   • Verify test start date is in the past
   • Check if test end date hasn’t passed
   • Ensure at least one variant is active

2. Rollout Strategy Issues

   • For Manual strategy: ensure variant IDs are specified
   • For Weighted strategy: check that weights sum to 100%
   • For Sequential strategy: verify rotation index is valid

3. Integration Problems

   • Check if A/B testing is enabled in SDK calls
   • Verify correct prompt ID is being used
   • Ensure sessionId is provided for consistent results

Inconsistent A/B Test Results

Symptoms:

• Same user gets different variants
• Test results seem random or incorrect
• Conversion tracking not working

Solutions:

1. Session Management

   • Provide consistent sessionId for each user
   • Use stable user identifiers
   • Check session ID format and consistency

2. Conversion Tracking

   • Verify conversion events are properly reported
   • Check that correct test and variant IDs are used
   • Ensure timing between prompt serving and conversion reporting

SDK Issues

Installation Problems

Package Installation Fails

Symptoms:

npm ERR! 404 Not Found
npm ERR! peer dep missing
Module not found: @promptcompose/sdk

Solutions:

1. NPM Registry Issues

   # Clear npm cache
   npm cache clean --force
   
   # Reinstall package
   npm uninstall @promptcompose/sdk
   npm install @promptcompose/sdk
   

2. Node Version Compatibility

   # Check Node version
   node --version
   
   # Upgrade if below 14.0.0
   # Use nvm to manage Node versions
   

3. Package Manager Issues

   # Try with yarn instead of npm
   yarn add @promptcompose/sdk
   
   # Or with pnpm
   pnpm add @promptcompose/sdk
   

TypeScript Compilation Errors

Symptoms:

Cannot find name 'PromptCompose'
Module '"@promptcompose/sdk"' has no exported member
Type errors in SDK usage

Solutions:

1. Import Statement Issues

   // Correct import
   import { PromptCompose } from '@promptcompose/sdk';
   
   // Not this
   import PromptCompose from '@promptcompose/sdk';
   

2. TypeScript Configuration

   // tsconfig.json
   {
     "compilerOptions": {
       "moduleResolution": "node",
       "esModuleInterop": true,
       "allowSyntheticDefaultImports": true
     }
   }
   

3. Type Declaration Issues

   # Reinstall with types
   npm install --save-dev @types/node
   

API Connection Issues

SDK Initialization Fails

Symptoms:

Error: Failed to initialize SDK
Error: Invalid API key or project ID
Network Error: Unable to connect

Solutions:

1. Credential Verification

   // Check credentials are loaded
   console.log('API Key:', process.env.PROMPT_COMPOSE_API_KEY ? 'Set' : 'Missing');
   console.log('Project ID:', process.env.PROMPT_COMPOSE_PROJECT_ID ? 'Set' : 'Missing');
   

2. Environment Variable Loading

   // Ensure dotenv is configured
   import dotenv from 'dotenv';
   dotenv.config();
   
   // Or use explicit path
   dotenv.config({ path: '.env.local' });
   

3. API URL Configuration

   // Check if custom API URL is needed
   process.env.PROMPT_COMPOSE_API_URL = 'https://api.promptcompose.io/api/v1';
   

Request Timeout Errors

Symptoms:

Error: Request timeout
Error: ECONNRESET
Error: Network timeout

Solutions:

1. Network Connectivity

   • Test internet connection
   • Check firewall settings
   • Try from different network

2. Timeout Configuration

   const promptCompose = new PromptCompose(
     apiKey,
     projectId,
     { 
       timeout: 30000, // 30 seconds
       retries: 3
     }
   );
   

3. Proxy Configuration

   // If behind corporate proxy
   process.env.HTTP_PROXY = 'http://proxy.company.com:8080';
   process.env.HTTPS_PROXY = 'https://proxy.company.com:8080';
   

Variable and Content Issues

Variable Validation Errors

Symptoms:

Error: Missing required variable(s): userName
Error: Variable 'age' must be a number
ValidationError: Invalid variable type

Solutions:

1. Check Variable Requirements

   // Examine prompt structure first
   const prompt = await promptCompose.getPrompt('prompt-id');
   console.log('Required variables:', 
     prompt.versions[0].variables
       .filter(v => v.required)
       .map(v => v.name)
   );
   

2. Type Validation

   // Ensure correct types
   const variables = {
     userName: 'John',        // string
     age: 25,                 // number
     isPremium: true,         // boolean
     preferences: ['email']   // array (if supported)
   };
   

3. Default Values

   // Provide defaults for optional variables
   const variables = {
     userName: userData.name || 'Guest',
     theme: userData.theme || 'light'
   };
   

Content Resolution Issues

Symptoms:

• Empty content returned
• Variables not interpolated
• Malformed output

Solutions:

1. Debug Content Resolution

   const result = await promptCompose.resolvePrompt(
     promptId, 
     { config: { debug: true } }, // Enable debug mode
     variables
   );
   
   console.log('Source:', result.source);
   console.log('Raw content:', result.content);
   

2. Encoding Issues

   // Check for encoding problems
   const content = result.content;
   console.log('Character length:', content.length);
   console.log('Byte length:', Buffer.byteLength(content, 'utf8'));
   

A/B Testing SDK Issues

A/B Test Integration Problems

Symptoms:

• A/B tests not triggering through SDK
• Same variant always returned
• Conversion reporting fails

Solutions:

1. Configuration Check

   // Verify A/B testing configuration
   const config = {
     config: {
       abTesting: {
         enabled: true, // Explicit enable
         sessionId: 'user-' + userId
       }
     }
   };
   

2. Session Consistency

   // Use consistent session IDs
   const sessionId = `${userId}-${deviceId}-${appVersion}`;
   
   const result = await promptCompose.resolvePrompt(promptId, {
     config: {
       abTesting: { sessionId }
     }
   });
   

3. Conversion Tracking Debug

   // Log conversion attempts
   try {
     await promptCompose.reportABResult(testId, {
       variantId: variantId,
       status: 'success',
       sessionId: sessionId
     });
     console.log('Conversion reported successfully');
   } catch (error) {
     console.error('Conversion reporting failed:', error.message);
     console.error('Test ID:', testId);
     console.error('Variant ID:', variantId);
     console.error('Session ID:', sessionId);
   }
   

Performance Issues

Slow API Responses

Symptoms:

• Long wait times for prompt resolution
• Timeout errors under load
• Degraded user experience

Solutions:

1. Implement Caching

   const cache = new Map();
   
   async function getCachedPrompt(promptId: string, variables: any) {
     const key = `${promptId}-${JSON.stringify(variables)}`;
     
     if (cache.has(key)) {
       return cache.get(key);
     }
     
     const result = await promptCompose.resolvePrompt(promptId, undefined, variables);
     cache.set(key, result);
     
     // Clear cache after 5 minutes
     setTimeout(() => cache.delete(key), 5 * 60 * 1000);
     
     return result;
   }
   

2. Batch Requests

   // Resolve multiple prompts efficiently
   const promises = promptIds.map(id => 
     promptCompose.resolvePrompt(id, config, variables)
   );
   
   const results = await Promise.all(promises);
   

3. Connection Pooling

   // Reuse SDK instance
   const promptCompose = new PromptCompose(apiKey, projectId);
   await promptCompose.init(); // Initialize once
   
   // Use the same instance for all requests
   

Memory Leaks

Symptoms:

• Memory usage increases over time
• Application becomes unresponsive
• Out of memory errors

Solutions:

1. Proper SDK Cleanup

   // Clean up resources
   process.on('SIGINT', () => {
     // Cleanup logic here
     process.exit();
   });
   

2. Cache Management

   // Implement cache size limits
   class LimitedCache {
     constructor(maxSize = 1000) {
       this.cache = new Map();
       this.maxSize = maxSize;
     }
     
     set(key, value) {
       if (this.cache.size >= this.maxSize) {
         const firstKey = this.cache.keys().next().value;
         this.cache.delete(firstKey);
       }
       this.cache.set(key, value);
     }
   }
   

Development Environment Issues

Local Development Setup

Environment Variables Not Loading

Symptoms:

• process.env variables are undefined
• “API key required” errors
• Development vs production config confusion

Solutions:

1. Environment File Location

   # Ensure .env file is in project root
   ls -la .env
   
   # Check file contents
   cat .env
   

2. Dotenv Configuration

   // Load before any other imports
   import dotenv from 'dotenv';
   dotenv.config();
   
   import { PromptCompose } from '@promptcompose/sdk';
   

3. Environment File Format

   # Correct format (no spaces around =)
   PROMPT_COMPOSE_API_KEY=pc_your_key_here
   PROMPT_COMPOSE_PROJECT_ID=proj_your_id_here
   
   # Not this
   PROMPT_COMPOSE_API_KEY = pc_your_key_here
   

CORS Issues in Browser

Symptoms:

Access to fetch blocked by CORS policy
CORS error when calling PromptCompose API

Solutions:

1. Use Server-Side API

   • Don’t call PromptCompose API directly from browser
   • Create backend endpoint that calls PromptCompose
   • Proxy requests through your server

2. Next.js API Routes

   // pages/api/prompts.ts
   export default async function handler(req, res) {
     const result = await promptCompose.resolvePrompt(
       req.body.promptId,
       req.body.config,
       req.body.variables
     );
     res.json(result);
   }
   

Production Issues

Deployment Problems

Environment Configuration

Symptoms:

• Works locally but fails in production
• Different behavior across environments
• Credential issues in deployed app

Solutions:

1. Environment Variable Setup

   # Verify production environment variables
   echo $PROMPT_COMPOSE_API_KEY
   echo $PROMPT_COMPOSE_PROJECT_ID
   

2. Container/Docker Issues

   # In Dockerfile, ensure ENV vars are set
   ENV PROMPT_COMPOSE_API_KEY=${PROMPT_COMPOSE_API_KEY}
   ENV PROMPT_COMPOSE_PROJECT_ID=${PROMPT_COMPOSE_PROJECT_ID}
   

3. Serverless Configuration

   # serverless.yml or similar
   environment:
     PROMPT_COMPOSE_API_KEY: ${env:PROMPT_COMPOSE_API_KEY}
     PROMPT_COMPOSE_PROJECT_ID: ${env:PROMPT_COMPOSE_PROJECT_ID}
   

Monitoring and Debugging

Enable Production Debugging

// Production-safe logging
class ProductionLogger {
  log(level: string, message: string, data?: any) {
    const entry = {
      timestamp: new Date().toISOString(),
      level,
      message,
      data,
      service: 'promptcompose'
    };
    
    console.log(JSON.stringify(entry));
  }
  
  error(message: string, error: Error) {
    this.log('error', message, {
      error: error.message,
      stack: error.stack
    });
  }
}

Getting Additional Help

Diagnostic Information

When contacting support, include:

1. Platform Issues:

   • Browser type and version
   • Operating system
   • Network configuration (proxy, VPN, etc.)
   • Error messages and screenshots
   • Steps to reproduce the issue

2. SDK Issues:

   • Node.js version (node --version)
   • SDK version (npm list @promptcompose/sdk)
   • Code snippets showing the issue
   • Full error messages including stack traces
   • Environment details (OS, runtime, etc.)

Debug Information Collection

// Collect debug information
async function collectDebugInfo() {
  const info = {
    nodeVersion: process.version,
    platform: process.platform,
    sdkVersion: require('@promptcompose/sdk/package.json').version,
    environment: process.env.NODE_ENV,
    timestamp: new Date().toISOString()
  };
  
  try {
    const connection = await promptCompose.init();
    info.connectionStatus = 'success';
    info.apiResponse = connection;
  } catch (error) {
    info.connectionStatus = 'failed';
    info.error = error.message;
  }
  
  console.log('Debug Info:', JSON.stringify(info, null, 2));
  return info;
}

Support Channels

1. Documentation: Review relevant guides and API references
2. FAQ: Check Frequently Asked Questions
3. Community: Join community discussions and forums
4. Support: Contact technical support with detailed information
5. GitHub: Report SDK issues with code examples

Prevention Best Practices

Regular Maintenance

1. Keep Dependencies Updated

   npm update @promptcompose/sdk
   npm audit fix
   

2. Monitor API Usage

   • Track API call volumes and patterns
   • Set up alerts for error rates
   • Monitor response times

3. Test Integrations

   • Regular integration tests
   • Monitor A/B test performance
   • Validate variable interpolation

Development Best Practices

1. Error Handling

   • Always wrap SDK calls in try-catch blocks
   • Provide fallback content for failed requests
   • Log errors with sufficient context

2. Testing

   • Unit tests for prompt integration logic
   • Integration tests for API connectivity
   • End-to-end tests for user workflows

3. Documentation

   • Document prompt usage and variables
   • Keep integration code well-commented
   • Maintain troubleshooting runbooks

By following this troubleshooting guide and implementing preventive measures, you can minimize issues and quickly resolve any problems that arise with PromptCompose.