Troubleshooting & Common Errors
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The FLEXT Plugin system utilizes a Railway-Oriented Programming (ROP) pattern to manage errors and maintain system stability. This approach wraps operations in a Result object (often cited as the r pattern), ensuring that failures are handled explicitly rather than through unmanaged exceptions. Troubleshooting in this environment involves identifying where in the lifecycle—discovery, initialization, activation, or execution—a component has deviated from the "happy path."
This guide outlines common error states, validation rules, and recovery protocols enforced by the FlextPluginPlatform and its associated domain models. It is designed to help developers diagnose issues related to plugin configuration, semantic versioning, and execution failures within the FLEXT ecosystem.
Sources: examples/basic-plugin.md:299-311, src/flext_plugin/models.py:20-30
Common Error States and Lifecycle Failures
Plugins within the system transition through various operational and error states. Identifying the current state of a plugin via the PluginStatus enum is the first step in troubleshooting.
Operational vs. Error Statuses
The system categorizes statuses to determine if a plugin can participate in workloads.
| Status Category | Status Values | Description |
|---|---|---|
| Operational | ACTIVE, HEALTHY, LOADED | Plugin is ready for execution or currently processing. |
| Error/Inactive | ERROR, UNHEALTHY, DISABLED, INACTIVE | Plugin is blocked from execution due to failure or administrative action. |
| Transient | LOADING, DISCOVERED | Plugin is in the process of transitioning states. |
Sources: tests/unit/test_models.py:30-45, src/flext_plugin/_utilities/plugin_platform.py:127-135
The Lifecycle Failure Flow
Errors typically occur when a plugin fails to meet the criteria for the next lifecycle stage. The following diagram illustrates the typical failure points during registration and execution.
The system requires explicit initialization before execution; attempting to run an uninitialized or inactive plugin results in a failure result.
Sources: src/flext_plugin/_utilities/plugin_platform.py:320-340, examples/basic-plugin.md:315-330
Validation and Configuration Errors
A significant portion of common errors stems from invalid metadata or configuration values that violate the domain's strict typing and business rules.
Semantic Versioning Violations
Plugins must adhere to a strict semantic versioning format (X.Y.Z). The FlextPluginModels.Plugin.Entity enforces this via validators.
- Error:
ValueError: Version must be semantic format X.Y.Z - Cause: Providing a version string like "1.0" (missing a part) or "1.a.0" (non-numeric).
- Resolution: Ensure exactly 2 to 3 numeric parts separated by dots.
Sources: src/flext_plugin/models.py:100-112, tests/unit/test_models.py:102-115
Business Rule Enforcement
The validate_business_rules() method checks for mandatory fields and data integrity before a plugin is registered.
| Rule | Constraint | Source File |
|---|---|---|
| Name | Must not be empty or whitespace only. | models.py:215 |
| Name Length | Regulated by MIN_PLUGIN_NAME_LENGTH and MAX_PLUGIN_NAME_LENGTH. | models.py:65 |
| Version | Must match VERSION_PATTERN. | models.py:76 |
| Description | Max length enforced by MAX_DESCRIPTION_LENGTH. | models.py:82 |
Sources: src/flext_plugin/models.py:65-90, src/flext_plugin/models.py:210-230
Execution Troubleshooting
When a plugin is active but fails during runtime, the system records metrics and specific error messages within the plugin's metadata.
Recording and Diagnosing Runtime Errors
The FlextPluginModels.Plugin.Entity class provides methods to capture failures:
record_error(error_message): Incrementserror_countand updateslast_errorin metadata.record_execution(time, success=False): Incrementsfailure_countand tracks total execution time.
Sources: src/flext_plugin/models.py:145-165, tests/unit/test_domain_entities.py:65-80
Execution Result Sequence
The PluginPlatformService manages the execution flow and captures failures at each stage of the composition.
Infrastructure and Integration Issues
Docker and Network Connectivity
For plugins integrating with external services (PostgreSQL, Redis, LDAP), connectivity failures are a common root cause. The system suggests a pre-connection check pattern.
- Symptom:
Result.fail("docker services unavailable") - Diagnostic Tool: Use
socket.connect_exto verify host and port availability before plugin activation. - Timeout Errors: Ensure
connection_timeoutin the plugin configuration matches the network latency of the Docker environment.
Sources: examples/03_docker_integration.py:20-35, examples/03_docker_integration.py:100-115
Protocol Configuration
The PluginPlatformService will fail if required protocols (Discovery, Loader, Executor) are not configured.
- Error:
Discovery protocol not configuredorLoader protocol not configured. - Fix: Ensure the platform instance has valid implementations assigned to
self.discovery,self.loader, orself.executor.
Sources: src/flext_plugin/_utilities/plugin_platform.py:304-310, src/flext_plugin/_utilities/plugin_platform.py:440-445
Recovery and Resolution Steps
The FLEXT engineering conduct (Universal Agent Law) dictates a "Fix-Forward" and "Root Cause Only" approach to resolving errors.
- Stop and Validate: Use the actual command and check the exit code. A non-zero exit code in example execution indicates a failure in the environment or configuration.
- Zero-Tolerance for Workarounds: Do not use
# type: ignoreorAnyto bypass validation errors. Fix the underlying model or configuration. - Clean Forward: If a plugin registration fails due to a conflict, do not revert the state; address the conflict in the current environment.
- Reset Statistics: If troubleshooting execution metrics, use
reset_statistics()to cleartotal_processedandtotal_errorscounters for a fresh baseline.
Sources: AGENTS.md:15-35, examples/basic-plugin.md:215-225, tests/unit/test_examples.py:25-35
Summary
Troubleshooting in the FLEXT Plugin system relies on the strict validation of domain entities and the explicit handling of Result objects. Most common errors are caught during the validation of semantic versions or business rules. When runtime errors occur, the platform's metadata tracking (error_count, last_error) and the railway-oriented execution flow provide the necessary telemetry to identify the root cause, whether it be uninitialized state, inactive status, or external connectivity issues in Docker environments.