[FAQ] Common issues and solutions when using apflow #10
Description
This issue documents common problems encountered when using apflow and their solutions. Updated as new issues are discovered and resolved.
1. ISO datetime 'Z' suffix parsing error (Python 3.10 and below)
Symptom: ValueError: Invalid isoformat string when passing datetime strings with 'Z' suffix.
Cause: Python 3.10's datetime.fromisoformat() does not support the 'Z' suffix (only Python 3.11+).
Solution (fixed in v0.15.0): Use parse_iso_datetime() helper from core/utils/helpers.py, which normalizes 'Z' to '+00:00' before parsing. All internal code has been updated.
2. Event loop conflicts in async CLI tests
Symptom: Tests hang with exit code 130 when combining @pytest.mark.asyncio with runner.invoke().
Cause: run_async_safe() attempts nested event loop execution inside pytest-asyncio's existing loop.
Solution (fixed in v0.11.0): ThreadPoolExecutor-based event loop isolation. Each async CLI operation runs in a separate thread with an independent event loop. See conftest.py for the implementation.
3. DuckDB concurrent write limitation
Symptom: Database lock errors when running both CLI and API server simultaneously.
Cause: DuckDB is a single-writer database. Only one process can write at a time.
Solution (addressed in v0.11.0): Use the CLI → API Gateway architecture. Configure api_server_url in config.cli.yaml, and all CLI writes route through the API server. For production with multiple writers, use PostgreSQL backend instead.
4. DuckDB custom path directory creation failure
Symptom: FileNotFoundError when specifying a custom DuckDB file path.
Cause: DuckDB does not create parent directories automatically.
Solution (fixed in v0.7.1): _ensure_database_directory_exists() now auto-creates parent directories. No user action needed on v0.7.1+.
5. Scheduler "Permission denied" when triggering tasks owned by other users
Symptom: Admin JWT tokens passed to webhook triggers return "Permission denied".
Cause: handle_webhook_trigger was not checking _is_admin(request), treating admin tokens as regular users.
Solution (fixed in v0.15.0): Admin check added to webhook trigger handler. Admin users get user_id=None, matching the pattern used by all other handlers.
6. Scheduled task re-execution produces stale results
Symptom: A scheduled parent task re-runs but its children retain completed status and old results from the previous cycle.
Cause: complete_scheduled_run() was not resetting child tasks before the next run.
Solution (fixed in v0.15.0): reset_task_tree_for_reexecution() now clears result, progress, and resets all children to pending before each scheduled re-execution.
7. CrewAI executor tests fail with OPENAI_API_KEY error
Symptom: Unit tests for CrewAI executors fail with OPENAI_API_KEY not set, even though tests should not call real APIs.
Cause: Missing mock patches for crewai.Agent and crewai.Task in test fixtures.
Solution (fixed in v0.18.0): Added crewai.Agent and crewai.Task patches in test_multi_phase_crew.py. Integration tests requiring real API keys now use api_keys_available fixture to skip when keys are not set.
8. Extension registration messages polluting CLI output
Symptom: Benign executor registration messages appear during normal CLI runs.
Cause: Registration messages were logged at INFO level.
Solution (fixed in v0.7.3): Registration messages demoted to DEBUG. Default log level is ERROR. Use LOG_LEVEL=DEBUG apflow ... to see them.
9. schemas.method field confusion in task definitions
Symptom: Task execution fails with "executor not found" when using placeholder values in schemas.method.
Cause: Documentation examples used placeholder values like "executor_id" instead of real executor IDs.
Solution (fixed in v0.7.2): All documentation examples updated to use valid executor IDs (e.g., "system_info_executor", "rest_executor", "command_executor"). The schemas.method field must match a registered executor ID.
Tips for Contributors
- Before opening a new issue, check if your problem is listed above.
- If you find a new common issue, comment below and we'll add it to this list.
- For executor-specific issues, include the executor ID and your input configuration.
- For database issues, specify your backend (DuckDB or PostgreSQL) and Python version.