Skip to main content

​
Known Issues & Technical Debt Tracker

This document tracks known issues, warnings, and technical debt discovered during development and testing.

​
FastAPI OpenAPI Duplicate Operation ID Warnings (Dashboard Routes)

First Seen: 2026-01-10 (pytest run in Docker) Evidence: 
api/tests/test_rate_plans_route_regression.py::test_rate_plans_route_in_openapi_schema
  /usr/local/lib/python3.11/site-packages/fastapi/openapi/utils.py:253: UserWarning: Duplicate Operation ID get_business_health_endpoint_api_v1_business_health_get for function get_business_health_endpoint at /app/api/routes/dashboard.py
    warnings.warn(message, stacklevel=1)

api/tests/test_rate_plans_route_regression.py::test_rate_plans_route_in_openapi_schema
  /usr/local/lib/python3.11/site-packages/fastapi/openapi/utils.py:253: UserWarning: Duplicate Operation ID get_agent_performance_endpoint_api_v1_agents_performance_get for function get_agent_performance_endpoint at /app/api/routes/dashboard.py
    warnings.warn(message, stacklevel=1)

api/tests/test_rate_plans_route_regression.py::test_rate_plans_route_in_openapi_schema
  /usr/local/lib/python3.11/site-packages/fastapi/openapi/utils.py:253: UserWarning: Duplicate Operation ID get_agent_growth_endpoint_api_v1_agents_growth_get for function get_agent_growth_endpoint at /app/api/routes/dashboard.py
    warnings.warn(message, stacklevel=1)
Likely cause (unconfirmed): Duplicate endpoint definitions exist in both api/main.py and api/routes/dashboard.py:
  • /api/v1/business-health: Defined in main.py (line 1702) and dashboard.py (line 336)
  • /api/v1/agents/performance: Defined in main.py (line 1614) and dashboard.py (line 361)
  • /api/v1/agents/growth: Defined in main.py (line 1758) and dashboard.py (line 390)
The dashboard router is included with prefix /api/v1 (line 2219 in main.py), causing FastAPI to generate duplicate operation IDs in the OpenAPI schema. Impact:
  • OpenAPI schema collisions can break client code generation
  • May hide endpoints or cause incorrect client bindings
  • Schema validation tools may fail
  • API documentation may be incomplete or incorrect
Scope:
  • Affects OpenAPI schema generation and client tooling
  • Not Phase 7C unless it affects commission endpoints
  • Routes are functional but schema is ambiguous
Next Debug Steps:
  1. Identify which routes share operation_id (already identified above)
  2. Remove duplicate definitions from main.py (keep router-based definitions in dashboard.py)
  3. OR assign explicit unique operation_id per route decorator: 
    @router.get("/business-health", operation_id="dashboard_get_business_health")
  4. Verify OpenAPI schema uniqueness after fix: app.openapi()["paths"]

​
Deprecated auth_users.yaml File (Legacy Auth)

First Seen: Unknown (documented in file header) Evidence: 
# api/config/auth_users.yaml
# DEPRECATED FOR LOGIN:
# Login now uses the BigQuery table payroll_analytics.dim_users exclusively.
# This file is kept only for admin/debug endpoints (e.g., /api/debug/users).
# DO NOT add new users here. New users must be created in dim_users instead.
Impact:
  • Risk of confusion: developers might add users to deprecated file
  • Maintenance burden: file exists but should not be used for login
  • Potential security risk if file is accidentally used instead of BigQuery dim_users
Scope:
  • Auth system migration (legacy → BigQuery)
  • Admin/debug endpoints still reference this file
Next Debug Steps:
  1. Audit all references to auth_users.yaml in codebase
  2. Migrate admin/debug endpoints to use dim_users table
  3. Remove file or add prominent deprecation warnings
  4. Update documentation to clarify migration status

​
Deprecated SECRET_KEY in auth.py (JWT Secret Fallback)

First Seen: Unknown (documented in code comments) Evidence: 
# api/auth.py line 48
# Legacy SECRET_KEY for backward compatibility (deprecated - use get_jwt_secret() instead)

# Line 99
logger.warning(f"[JWT-SECRET] Using config fallback in production - should use JWT_SECRET_KEY env var, Fingerprint: {secret_fingerprint}")
Impact:
  • Security risk: fallback to config file in production (line 99 warning)
  • Code complexity: multiple secret resolution paths
  • Potential for misconfiguration
Scope:
  • JWT authentication system
  • Production deployments should use JWT_SECRET_KEY env var
Next Debug Steps:
  1. Verify all production deployments use JWT_SECRET_KEY env var
  2. Remove config file fallback (or make it dev-only)
  3. Update deployment documentation to require env var
  4. Add startup validation to fail fast if secret not found in production

​
Stage 3 TPA Normalization: Print Statements Instead of Logger

First Seen: Unknown (code review) Evidence: 
# stage3_absorb/apply_tpa_normalization.py
print("   WARNING: employee_count missing, using absorbed_count as fallback")
print("   WARNING: employee_count not found, using 1 per record")
print("   WARNING: No TPA records to process")
print(f"\n   WARNING: {mixed_cadence_mask.sum():,} records with MIXED pay_periods flag")
print("   WARNING: employee_count missing, setting to absorbed_count")
Impact:
  • Warnings not captured in application logs
  • Cannot filter/suppress warnings in production
  • Inconsistent logging pattern (other modules use logger.warning())
Scope:
  • Stage 3 TPA normalization pipeline
  • Affects observability and debugging
Next Debug Steps:
  1. Replace print() statements with logger.warning() or logger.info()
  2. Ensure logger is initialized in module
  3. Verify warnings appear in application logs
  4. Consider log level configuration for production vs development

​
Pydantic Deprecation Warnings (V2 Migration)

First Seen: 2026-01-10 (pytest run in Docker) Evidence: 
/usr/local/lib/python3.11/site-packages/pydantic/fields.py:799: PydanticDeprecatedSince20: Using extra keyword arguments on `Field` is deprecated and will be removed. Use `json_schema_extra` instead. (Extra keys: 'example'). Deprecated in Pydantic V2.0 to be removed in V3.0.

/usr/local/lib/python3.11/site-packages/pydantic/_internal/_config.py:268: PydanticDeprecatedSince20: Support for class-based `config` is deprecated, use ConfigDict instead. Deprecated in Pydantic V2.0 to be removed in V3.0.

/usr/local/lib/python3.11/site-packages/pydantic/_internal/_generate_schema.py:252: PydanticDeprecatedSince20: `json_encoders` is deprecated. See https://docs.pydantic.dev/2.5/concepts/serialization/#custom-serializers for alternatives.
Impact:
  • Code will break when Pydantic V3.0 is released
  • 1079 deprecation warnings in test output (noise)
  • Migration effort required before V3.0 release
Scope:
  • All Pydantic model definitions (schemas, request/response models)
  • Not Phase 7C unless commission schemas are affected
Next Debug Steps:
  1. Audit Pydantic model usage across codebase
  2. Migrate Field(example=...) → Field(json_schema_extra={"example": ...})
  3. Migrate class-based config → ConfigDict
  4. Replace json_encoders with custom serializers
  5. Create migration checklist and prioritize high-traffic schemas

​
FastAPI on_event Deprecation Warning

First Seen: 2026-01-10 (pytest run in Docker) Evidence: 
/app/api/main.py:231: DeprecationWarning: 
        on_event is deprecated, use lifespan event handlers instead.
        
        Read more about it in the
        [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/).
        
    @app.on_event("startup")
Impact:
  • Code will break when FastAPI removes on_event support
  • Migration to lifespan handlers required
Scope:
  • FastAPI application startup/shutdown events
  • Single occurrence in main.py line 231
Next Debug Steps:
  1. Migrate @app.on_event("startup") → lifespan context manager
  2. Migrate @app.on_event("shutdown") → lifespan context manager
  3. Test startup/shutdown behavior after migration
  4. Update FastAPI version compatibility notes

​
Python Crypt Module Deprecation Warning

First Seen: 2026-01-10 (pytest run in Docker) Evidence: 
/usr/local/lib/python3.11/site-packages/passlib/utils/__init__.py:854: DeprecationWarning: 'crypt' is deprecated and slated for removal in Python 3.13
    from crypt import crypt as _crypt
Impact:
  • Code will break when Python 3.13 removes crypt module
  • Dependency (passlib) uses deprecated module
  • Requires passlib update or alternative password hashing library
Scope:
  • Password hashing (passlib dependency)
  • Affects authentication system
Next Debug Steps:
  1. Check passlib version and update if newer version available
  2. Monitor passlib GitHub for Python 3.13 compatibility
  3. Consider alternative password hashing library if passlib doesn’t update
  4. Test password verification after any library changes

​
BigQuery Client Fallback Warnings

First Seen: Unknown (code review) Evidence: 
# api/bigquery/queries.py (multiple locations)
logger.warning("BigQuery client not available, using mock data")
logger.warning("BigQuery client not available, returning empty list")
Impact:
  • Silent fallbacks to mock/empty data may hide configuration issues
  • Production deployments may return incorrect data if BigQuery is misconfigured
  • Difficult to distinguish between “no data” and “client unavailable”
Scope:
  • All BigQuery query functions
  • Affects data accuracy and observability
Next Debug Steps:
  1. Audit all BigQuery client fallback patterns
  2. Consider failing fast in production (raise exception instead of mock data)
  3. Add health check endpoint to verify BigQuery connectivity
  4. Improve error messages to distinguish configuration vs data issues

​
Orchestrator Pipeline: Multiple Warning Conditions

First Seen: Unknown (code review) Evidence: 
# orchestrator.py
self.logger.warning("ANOMALY ALERT: {business_loss} businesses missing from Stage 3")
self.logger.warning("CRITICAL: Large financial loss of ${financial_loss:,.2f}")
self.logger.warning("CRITICAL: Owner Commission < 25%")
self.logger.warning("CRITICAL: TPA Commission > 75%")
self.logger.warning("CRITICAL: {len(dropped_negative_businesses)} businesses with negative totals were dropped!")
Impact:
  • Many warning conditions may indicate data quality issues
  • Some warnings are marked “CRITICAL” but don’t fail the pipeline
  • May hide real problems if warnings are ignored
Scope:
  • Payroll pipeline execution
  • Data quality validation
Next Debug Steps:
  1. Review which warnings should be errors (fail pipeline)
  2. Add metrics/alerting for critical warnings
  3. Document expected warning scenarios vs anomalies
  4. Consider structured logging for better alerting integration

​
Notes

  • Issues are tracked chronologically by “First Seen” date when available
  • Priority should be assigned based on impact and scope
  • Some issues may be acceptable technical debt (documented deprecations)
  • Production-critical issues should be addressed before Phase 7C completion