Skip to main content

Troubleshooting Guide

Common issues, error messages, and their solutions for Axiom Genesis platform.

Quick Diagnostics​

Health Check Endpoints​

# API health
curl https://api.axiomgenesis.com/health

# Database connectivity
curl https://api.axiomgenesis.com/health/db

# Redis connectivity
curl https://api.axiomgenesis.com/health/redis

Authentication Issues​

401 Unauthorized​

Symptoms: API returns 401 for all requests

Common Causes:

  1. Expired JWT token - Token has exceeded its TTL
  2. Missing tenant header - x-tenant-id header not provided for pre-login requests
  3. Invalid tenant encryption - Tenant ID not properly encrypted

Solutions:

// Ensure apiClient includes interceptors
import { apiClient } from '@/lib/apiClient';

// Check token expiration
const token = localStorage.getItem('token');
const decoded = jwt_decode(token);
if (decoded.exp < Date.now() / 1000) {
  // Token expired, redirect to login
}

403 Forbidden​

Symptoms: User authenticated but cannot access resource

Common Causes:

  1. Role permissions - User's role lacks required permission
  2. Tenant isolation - Attempting to access another tenant's data
  3. Feature flag - Feature disabled for tenant

Solutions:

  • Check app_roles.rol_permissions for user's role
  • Verify tenant_id in request matches user's tenant
  • Check app_tenants.tnt_features for feature flags

Database Issues​

Connection Pool Exhausted​

Symptoms: ECONNREFUSED or pool exhausted errors

Solutions:

// Check pool configuration in db_connections.js
const poolConfig = {
  max: 100,          // Increase if needed
  min: 10,
  idleTimeoutMillis: 30000,
  acquireTimeoutMillis: 60000
};

Query Timeout​

Symptoms: Queries hanging or timing out

Solutions:

  1. Check for missing indexes on filtered columns
  2. Verify tenant_id is indexed
  3. Use query analyzer:
SET STATISTICS IO ON;
SET STATISTICS TIME ON;
-- Run your query
SET STATISTICS IO OFF;
SET STATISTICS TIME OFF;

Frontend Issues​

Redux State Not Updating​

Symptoms: UI not reflecting latest data

Common Causes:

  1. Immutability violation - State mutated directly
  2. Selector memoization - Stale selector cache
  3. Missing dispatch - Action not dispatched

Solutions:

// Use typed hooks
import { useAppSelector, useAppDispatch } from '@/store/hooks';

// Verify action is dispatched
const dispatch = useAppDispatch();
dispatch(setUser(userData)); // Check this is called

DataView Not Loading​

Symptoms: DataViewer shows loading spinner indefinitely

Debugging:

  1. Check browser Network tab for API response
  2. Verify dvc_code exists in app_dataview_configs
  3. Check console for JavaScript errors
// Debug dataview loading
console.log('DataView code:', dataviewCode);
console.log('API response:', response.data);

Workflow Issues​

Workflow Instance Stuck​

Symptoms: Workflow instance in PENDING or RUNNING state indefinitely

Diagnosis:

-- Check instance status
SELECT wfi_id, wfi_status, wfi_current_node, wfi_error_message
FROM wft_instances 
WHERE wfi_id = @instanceId;

-- Check node states
SELECT wns_node_id, wns_status, wns_error
FROM wft_node_states 
WHERE wns_instance_id = @instanceId;

Solutions:

  1. Check worker process is running: npm run start:worker
  2. Verify Redis connection for queue
  3. Check wft_logs for error details

Node Execution Failed​

Symptoms: Node shows FAILED status

Debugging:

-- Get detailed error
SELECT wfl_message, wfl_data
FROM wft_logs 
WHERE wfl_instance_id = @instanceId 
  AND wfl_level = 'error'
ORDER BY wfl_created_at DESC;

Redis Issues​

Cache Invalidation​

Symptoms: Stale data after updates

Solutions:

# Clear specific cache
redis-cli DEL "obj_registry:users"

# Clear all entity caches
redis-cli KEYS "obj_registry:*" | xargs redis-cli DEL

Connection Failed​

Symptoms: ECONNREFUSED to Redis

Solutions:

  1. Verify Redis is running: redis-cli ping
  2. Check REDIS_HOST and REDIS_PORT environment variables
  3. For Azure Redis, ensure TLS is enabled:
const redisConfig = {
  tls: process.env.NODE_ENV === 'production' ? {} : undefined
};

Build Issues​

TypeScript Errors​

Symptoms: Build fails with type errors

Solutions:

# Run type check
npm run type-check

# Clear TypeScript cache
rm -rf node_modules/.cache/typescript

Out of Memory​

Symptoms: JavaScript heap out of memory

Solutions:

# Increase Node memory (already in package.json)
NODE_OPTIONS=--max-old-space-size=8192 npm run build

Getting Help​

If issues persist:

  1. Check the FAQ for common questions
  2. Review Architecture Decision Records for design context
  3. Search existing issues in the repository
  4. Contact the development team with:
    • Error message/stack trace
    • Steps to reproduce
    • Environment details (Node version, browser, etc.)