Skip to main content
Version: Next

Troubleshooting Article Template

Use this template when creating troubleshooting documentation for common issues with Apache AGE Schema Client.

Troubleshooting: [Problem Category or Specific Issue]

Brief description of the problem area this article covers and who might encounter these issues.

Quick Diagnosis​

Symptoms Checklist​

Check if you're experiencing any of these symptoms:

  • Symptom 1: Description of what the user sees
  • Symptom 2: Error message or unexpected behavior
  • Symptom 3: Performance issue or timeout
  • Symptom 4: Configuration or setup problem

Common Causes​

The most frequent causes of these issues are:

  1. Configuration problems: Incorrect database settings or connection parameters
  2. Schema mismatches: Data doesn't match the defined schema
  3. Permission issues: Database user lacks necessary permissions
  4. Version conflicts: Incompatible versions of dependencies

Detailed Troubleshooting​

Issue 1: [Specific Problem Title]​

Problem Description​

Clear description of the specific issue, including:

  • When it typically occurs
  • What triggers the problem
  • Impact on the application

Symptoms​

Error Message:

Exact error message that users see

Behavior:

  • What happens instead of the expected behavior
  • Any side effects or related issues

Root Cause​

Explanation of why this problem occurs:

  • Technical explanation of the underlying issue
  • Common scenarios that lead to this problem
  • Dependencies or configurations involved

Solution​

Step-by-step resolution:

  1. Verify the problem: How to confirm this is the actual issue

    // Diagnostic code to verify the issue
    try {
      const result = await problematicOperation();
      console.log('Operation succeeded:', result);
    } catch (error) {
      console.error('Confirmed issue:', error.message);
    }

  2. Apply the fix: Detailed instructions for resolution

    // Corrected code or configuration
    const correctedConfiguration = {
      // Proper settings
      setting1: 'correctValue',
      setting2: true
    };

    const fixedOperation = new OperationClass(correctedConfiguration);

  3. Verify the solution: How to confirm the fix worked

    // Verification code
    const testResult = await fixedOperation.test();
    console.log('Fix verified:', testResult.success);

Prevention​

How to avoid this issue in the future:

  • Configuration best practices
  • Code patterns to follow
  • Monitoring or validation to implement

Issue 2: [Another Specific Problem]​

Problem Description​

Description of the second issue...

Symptoms​

Error Message:

Another error message

Behavior:

  • Different symptoms for this issue

Root Cause​

Why this different problem occurs...

Solution​

  1. Step 1: First resolution step

    // Solution code

  2. Step 2: Additional steps

Prevention​

Prevention strategies for this issue...

Advanced Troubleshooting​

Debugging Techniques​

Enable Debug Logging​

// Enable detailed logging for troubleshooting
import { setLogLevel } from 'age-schema-client';

setLogLevel('debug');

// Your application code
const result = await operation();

Connection Diagnostics​

// Test database connectivity
import { PgConnectionManager } from 'age-schema-client';

async function testConnection() {
  const manager = new PgConnectionManager({
    host: 'localhost',
    port: 5432,
    database: 'postgres',
    user: 'postgres',
    password: 'postgres'
  });

  try {
    const connection = await manager.getConnection();
    console.log('Connection successful');

    // Test Apache AGE availability
    const result = await connection.query("SELECT * FROM ag_catalog.ag_graph LIMIT 1");
    console.log('Apache AGE available:', result.rows.length >= 0);

    connection.release();
  } catch (error) {
    console.error('Connection failed:', error.message);
  }
}

Schema Validation Testing​

// Test schema validation
import { SchemaValidator } from 'age-schema-client';

const validator = new SchemaValidator(yourSchema);

// Test specific data
const testData = { /* your test data */ };
const validationResult = validator.validate('VertexType', testData);

if (!validationResult.valid) {
  console.error('Validation errors:', validationResult.errors);
}

Performance Diagnostics​

Query Performance Analysis​

// Measure query performance
const startTime = Date.now();

try {
  const result = await queryExecutor.executeCypher(cypherQuery, params, graphName);
  const duration = Date.now() - startTime;

  console.log(`Query completed in ${duration}ms`);
  console.log(`Returned ${result.rows.length} rows`);

} catch (error) {
  const duration = Date.now() - startTime;
  console.error(`Query failed after ${duration}ms:`, error.message);
}

Memory Usage Monitoring​

// Monitor memory usage during batch operations
const initialMemory = process.memoryUsage();

await batchLoader.loadData(largeDataset);

const finalMemory = process.memoryUsage();
const memoryIncrease = finalMemory.heapUsed - initialMemory.heapUsed;

console.log(`Memory increase: ${Math.round(memoryIncrease / 1024 / 1024)}MB`);

Environment-Specific Issues​

Development Environment​

Common issues in development:

  • Local database setup: Configuration problems
  • Version mismatches: Different versions between team members
  • Test data conflicts: Shared test database issues

Production Environment​

Production-specific considerations:

  • Connection pooling: Pool exhaustion or configuration
  • Performance: Query optimization and indexing
  • Monitoring: Logging and alerting setup

Docker/Container Issues​

Container-specific problems:

  • Network connectivity: Container networking issues
  • Environment variables: Configuration in containerized environments
  • Volume mounting: Database persistence issues

Getting Additional Help​

Before Asking for Help​

  1. Check this documentation: Review all relevant troubleshooting guides
  2. Search existing issues: Look for similar problems in the issue tracker
  3. Gather information: Collect logs, error messages, and configuration details
  4. Create a minimal reproduction: Isolate the problem to its simplest form

Information to Include​

When reporting issues, include:

  • Environment details: Node.js version, library version, OS
  • Configuration: Database settings (without sensitive information)
  • Error messages: Complete error messages and stack traces
  • Code samples: Minimal code that reproduces the issue
  • Expected vs actual behavior: What you expected and what happened

Where to Get Help​

  • GitHub Issues: [Link to issue tracker] for bugs and feature requests
  • Discussions: [Link to discussions] for questions and community help
  • Documentation: [Link to main docs] for comprehensive guides
  • Examples: [Link to examples] for working code samples
  • [Main Troubleshooting Guide]: [Link to comprehensive troubleshooting]
  • [Configuration Guide]: [Link to configuration documentation]
  • [Performance Guide]: [Link to performance optimization]
  • [Security Guide]: [Link to security best practices]

Template Usage Instructions​

When to Use This Template​

Use this template for:

  • Common error scenarios: Frequently reported issues
  • Complex problems: Multi-step troubleshooting processes
  • Environment-specific issues: Platform or setup-related problems
  • Performance problems: Optimization and debugging guides

Structure Guidelines​

Problem-Solution Format​

  • Start with clear problem identification
  • Provide step-by-step solutions
  • Include verification steps
  • Offer prevention strategies

Diagnostic Approach​

  • Help users identify the root cause
  • Provide tools for investigation
  • Offer multiple solution paths
  • Include escalation options

Writing Tips​

Be Systematic​

  • Use consistent problem-solving methodology
  • Provide clear diagnostic steps
  • Offer multiple approaches when applicable
  • Include verification for each solution

Include Context​

  • Explain why problems occur
  • Provide background on technical concepts
  • Connect to broader system understanding
  • Reference related documentation

Make It Actionable​

  • Provide specific, executable solutions
  • Include working code examples
  • Offer clear success criteria
  • Suggest prevention strategies

Quality Checklist​

Before publishing troubleshooting documentation:

  • Accurate: All solutions have been tested
  • Complete: Covers the most common scenarios
  • Clear: Instructions are unambiguous
  • Helpful: Provides genuine value to users
  • Current: Uses current APIs and best practices
  • Accessible: Appropriate for the target audience

Maintenance​

  • Monitor feedback: Track which solutions work
  • Update regularly: Keep solutions current with library changes
  • Add new issues: Document newly discovered problems
  • Improve clarity: Refine based on user questions