Epochly User Guide: Troubleshooting

Common issues and their solutions.

Diagnostic Tool

Run the built-in diagnostic:

epochly doctor

This checks:

• Installation integrity
• License status
• System compatibility
• Current configuration

Common Issues

No Performance Improvement

Symptoms: Code runs at same speed with Epochly.

Causes:

1. Workload is I/O-bound (not CPU-bound)
2. Code already uses optimized libraries (NumPy)
3. Workload too small (overhead > benefit)

Solution:

import epochly
metrics = epochly.get_metrics()
print(metrics)  # Shows optimization stats and recommendations

Stuck at Level 0

Symptoms: Enhancement level never increases.

Causes:

1. Function not called enough times
2. Unstable output detected
3. License limits reached

Solution:

import epochly
status = epochly.get_status()
print(status)  # dict with current status info

JIT Compilation Fails

Symptoms: Level 2 not activating.

Causes:

1. Unsupported Python constructs
2. Dynamic typing issues
3. External library calls

Solution:

from epochly.jit import get_jit_compatibility_info
report = get_jit_compatibility_info()
print(report['available_backends'])
print(report['recommended_backend'])

Memory Issues

Symptoms: High memory usage or OOM errors.

Solution:

epochly.configure(
    memory_limit_gb=8,
    pool_size_mb=256
)

Async or Event-Loop Workloads Slowing Down

Symptoms: Async code (asyncio, aiohttp, FastAPI) runs slower with Epochly. Level 3 (Multicore) causes interference with event loops or sub-interpreter conflicts.

Solution: Cap the maximum enhancement level to prevent Level 3 activation:

export EPOCHLY_MAX_LEVEL=2

This keeps JIT compilation (Level 2) active while preventing sub-interpreter parallelism (Level 3) from interfering with async workloads. You can set this per-service or globally.

When to use EPOCHLY_MAX_LEVEL:

• Async/event-loop services where Level 3 causes regressions
• Workloads where you want JIT but not multicore parallelism
• Gradual rollout: start capped at Level 2, then test Level 3 separately

Getting Help

• GitHub Issues: github.com/epochly/epochly/issues
• Documentation: /docs (this site)
• Email: support@epochly.com