Flaxon 0.3.0 and Teloce-Py 0.3.0 are available on PyPI. Release instructions are maintained on this site; source links identify the framework snapshot. Check version and upgrade guidance.

Framework source · Markdown

Debugging

Overview

Flaxon includes a built-in debugging system designed to help developers identify and fix application issues quickly.

The debugger provides:

• Clear error explanations
• Error codes
• Request context
• Stack traces during development
• Recorded application errors
• Issue history
• Sensitive data redaction
• Debugging information through a web interface

Flaxon's goal is to make debugging easier by explaining what happened, why it happened, and where to fix it.

Debug Mode

Debug mode enables detailed error reporting and the debugging dashboard.

Enabling Debug Mode

Using Application Configuration

from flaxon import Flaxon


app = Flaxon(
    "my-app",
    debug=True
)
````

---

### Using Configuration Options

```python
from flaxon import Flaxon


app = Flaxon(
    "my-app",
    config={
        "DEBUG": True
    }
)

Debug Dashboard

When debug mode is enabled, Flaxon provides a local debugging dashboard.

Open:

http://localhost:8000/__debug__

The dashboard displays:

• Recorded errors
• Application exceptions
• Request information
• Error timestamps
• Error frequency
• Stack traces
• Error codes
• Debug logs

Example:

Flaxon Debug Dashboard

Application:
my-app

Status:
Development Mode


Recent Errors:

[FX-404]
RouteNotFoundError

Time:
2026-08-03 10:30:15


[FX-500]
DatabaseConnectionError

Time:
2026-08-03 10:32:04

Error Recording

Flaxon automatically records errors during development.

Each error entry contains:

Error Codes

Flaxon uses structured error codes to make issues easier to identify.

Example:

raise HTTPException(
    404,
    "User not found",
    code="FX-USER-404"
)

Example codes:

Request Context

The debugger includes useful request information:

Example:

Request

Method:
POST

Path:
/api/users

Request ID:
fx-a82c91

IP:
127.0.0.1

Headers:
Content-Type: application/json

Sensitive values are automatically hidden.

Sensitive Data Protection

The debugger removes sensitive information from logs.

Protected values include:

• Passwords
• Authentication tokens
• API keys
• Secrets
• Private keys
• Authorization headers
• Payment information

Example:

Before:

password=myPassword123

After:

password=[REDACTED]

Debugging Exceptions

Example:

@app.get("/users/<int:user_id>")
async def get_user(user_id: int):

    user = await database.find_user(
        user_id
    )

    return user.name

If user is missing, the debugger provides:

Error:
AttributeError

Message:
User object is None

Location:
app.py line 12

Suggestion:
Check if the database query returned a valid user.

Clearing Debug Records

During development, stored errors can be cleared.

Example:

flaxon debug clear

Production Safety

Debug mode should never be enabled in production.

Disable:

app = Flaxon(
    "my-app",
    debug=False
)

Production mode:

• Hides stack traces
• Returns safe error messages
• Prevents debug dashboard access
• Protects sensitive information

Debugging Workflow

Recommended workflow:

1. Enable debug mode.

app = Flaxon(
    "my-app",
    debug=True
)

1. Start the application.

flaxon run app:app --reload

1. Open:

http://localhost:8000/__debug__

1. Review recorded errors.

2. Fix the issue.

3. Restart the application.

Best Practices

For effective debugging:

• Use meaningful error codes.
• Include request IDs in logs.
• Keep debug mode limited to development.
• Never expose debug dashboards publicly.
• Review logs before deploying.
• Use monitoring tools for production systems.

Next Steps

Related documentation:

• Security
• Performance
• Configuration
• Architecture

Use this capability in a full-stack app

Flaxon serves Python APIs and Teloce interfaces in one project. Keep validation, authorization and privileged operations on the server; components call those endpoints and present their results. Follow the full-stack lessons and Teloce integration reference to connect this capability to pages, components and application modules.

Teloce browser and SSR diagnostics

Compiled Teloce pages receive a development-only overlay and bounded reporter when debug=True. Compiler, SSR, runtime, hydration and failed API diagnostics appear in the same dashboard; request IDs connect API reports to server errors. See Teloce SSR and browser debugging for setup, source mapping limits, reporting safeguards and production behavior.