Troubleshooting Guide

Relevant source files

The following files were used as context for generating this wiki page:

• troubleshooting.md
• guides/troubleshooting.md
• guides/development.md
• development.md
• guides/configuration.md
• guides/testing.md

This guide provides comprehensive diagnostic procedures, common issue resolutions, and debugging techniques for the FLEXT platform and specifically the flext-web component. It serves as a central reference for developers and operators to maintain system health and resolve technical debt or runtime failures within the environment. Sources: guides/troubleshooting.md:1-25, troubleshooting.md:1-5

FLEXT utilizes strict architectural patterns, including Railway-Oriented Programming (using the r result pattern) and mandatory type safety. Troubleshooting efforts must respect these boundaries, focusing on the public facade and validated settings models. Sources: guides/development.md:105-135, development.md:15-30

Quick Diagnosis and Health Checks

The first step in any troubleshooting workflow is to verify the current state of the environment and dependencies. FLEXT provides standardized make targets to validate code quality and system health. Sources: guides/troubleshooting.md:27-45, development.md:24-28

Health Check Commands

Command	Purpose
make val	Performs a full system validation (lint, types, tests, security).
make lint	Checks code quality and style using Ruff.
make type-check	Validates type safety using MyPy/Pyrefly.
make test	Executes the full test suite.
make security	Scans for security vulnerabilities using Bandit.

Sources: guides/troubleshooting.md:29-45, guides/development.md:180-195

Diagnostic Flow

The following diagram illustrates the recommended sequence for diagnosing issues within a FLEXT project.

Common Issues and Solutions

1. Import and Environment Errors

Module resolution failures typically stem from incorrect PYTHONPATH configurations or incomplete dependency installations in the Poetry environment. Sources: guides/troubleshooting.md:59-75, guides/development.md:252-260

• Symptoms: ModuleNotFoundError: No module named 'flext_core' or flext_web.
• Resolution:
  1. Ensure export PYTHONPATH=src is set in your shell.
  2. Run make clean && make setup to reinstall the workspace.
  3. Verify the environment with poetry env info.

Sources: guides/troubleshooting.md:65-75, troubleshooting.md:10-15

2. Configuration and Settings Failures

Configuration in FLEXT is hierarchical and validated via Pydantic v2. Failures usually occur due to missing required fields or invalid environment variable prefixes. Sources: guides/configuration.md:16-25, guides/troubleshooting.md:120-135

• Validation Check: Use u.Web.validate_settings(runtime_settings).unwrap() to inspect why a configuration model fails to initialize. Sources: troubleshooting.md:20-22
• Env Inspection: Check variables with env | grep FLEXT_. Sources: guides/troubleshooting.md:126

3. Type Safety Violations

FLEXT enforces "Zero Tolerance" for missing or incorrect type annotations. MyPy errors must be resolved by adhering to the t.JsonMapping and p.Result[T] patterns. Sources: guides/development.md:92-103, guides/troubleshooting.md:96-105

• Common Fix: Ensure functions return p.Result[T] rather than raising exceptions. Use r.ok() and r.fail() to maintain the railway pipeline. Sources: guides/development.md:110-120, guides/troubleshooting.md:100-104

Runtime and Service Debugging

For flext-web specifically, issues often center on route initialization or middleware configuration. Sources: troubleshooting.md:25-30

Service Lifecycle Verification

If the web service fails to start, verify the facade initialization sequence:

from flext_web import web

# Step-by-step lifecycle check
assert web.initialize_routes().success
assert web.configure_middleware().success
assert web.get_service_status().success

Sources: troubleshooting.md:27-33, development/README.md:25-35

Performance Troubleshooting

FLEXT components like LDIF processing can encounter memory or CPU bottlenecks when handling large datasets.

• Memory Issues: Monitor with psutil. If RSS exceeds 500MB, consider reducing batch_size in FlextLdifSettings. Sources: guides/troubleshooting.md:235-255
• CPU Optimization: Enable parallel_processing=True and adjust max_workers based on available cores. Sources: guides/troubleshooting.md:205-215

Error Code Reference

FLEXT uses standardized error codes to identify failure points across different layers of the stack. Sources: guides/troubleshooting.md:280-310

Code Category	Scope	Common Cause
FLEXT_00X	Core	Configuration validation or Dependency Injection failures.
LDIF_00X	Data	Parsing syntax errors or server compatibility issues.
API_00X	Network	Connection timeouts or authentication failures.

Sources: guides/troubleshooting.md:280-305

Testing and Troubleshooting

When tests fail, FLEXT mandates the use of verbose output and debugging hooks to isolate the regression. Sources: guides/testing.md:465-485

Debugging Test Failures

# Run a specific failing test with debugger entry
pytest tests/unit/test_module.py::TestClass::test_method -v --pdb

Sources: guides/troubleshooting.md:113-115, guides/development.md:246-250

Coverage Gates

Ensure that troubleshooting efforts do not drop coverage below the project thresholds (85% for core libraries, 75% for applications). Run make test to verify compliance with [tool.coverage] settings in pyproject.toml. Sources: guides/testing.md:26-35, pyproject.toml:98-105

Conclusion

Troubleshooting in the FLEXT ecosystem requires a systematic approach that respects the platform's commitment to type safety and functional error handling. By utilizing the provided make targets, validating configuration via Pydantic, and verifying service state through the public facade, developers can efficiently resolve issues while maintaining the system's "zero-debt" baseline. Sources: guides/troubleshooting.md:405-415, index.md:32-38