Compozy Symbol
ALPHA
DocsInstallGetting StartedFeaturesPricing
Quick StartDatabaseDeploymentConfigurationKnowledge BasesArchitectureTroubleshootingGuidesCoreCLI ReferenceSchema DefinitionAPI Reference

Temporal Troubleshooting

Resolve common issues when running Temporal in Compozy.

Quick Diagnostics

  • Check ports

    lsof -i :7233-7236 shows which process is using Temporal service ports. Release conflicting processes or configure a different frontend_port.

  • Inspect logs

    Run COMPOZY_LOG_LEVEL=debug and set temporal.standalone.log_level=debug to stream Temporal server logs through the CLI.

  • Validate namespace

    temporal namespace describe confirms the namespace exists and is reachable when operating in remote mode.

Port Conflicts

SymptomResolution
listen tcp 127.0.0.1:7233: bind: address already in useChange temporal.standalone.frontend_port (all services shift with it) or stop the conflicting process.
Temporal UI fails to start because 8233 is in useSet temporal.standalone.ui_port to an available port or disable the UI with enable_ui: false.
Remote mode cannot reach TemporalVerify firewall rules and TLS configuration. Use temporal workflow list --namespace <ns> from the same host.

SQLite Issues

  • Permission denied

    Ensure the directory containing database_file exists and is writable. For CI, create a tmp directory before launching Compozy.

  • Corrupted database

    Delete the SQLite file and restart. Use :memory: for transient runs or swap to a clean path per test.

  • Slow startup

    Large disk-backed SQLite files slow boot time. Prune old history or use :memory: during development.

Startup Timeouts

If you see standalone Temporal failed to start within 30s:

  • Increase temporal.standalone.start_timeout (e.g. 60s) for slower laptops or CI.
  • Check that the host ports are free; Temporal will not start if they are already bound.
  • For remote mode, confirm the Temporal cluster is reachable and healthy. Latency or TLS negotiation failures can exhaust the timeout.

Temporal UI Not Accessible

  • Confirm enable_ui: true and that the UI port is open.
  • For standalone mode, open http://127.0.0.1:<ui_port>. If you bound to 0.0.0.0, use the machine IP explicitly.
  • Behind reverse proxies, configure allowed hosts and TLS termination before exposing the UI to other users.

Performance & Throughput

  • Standalone mode uses SQLite and a single worker process—expect lower throughput than production clusters.
  • To simulate production load, switch to remote mode against a staging Temporal cluster.
  • Monitor metrics via Compozy’s Prometheus endpoint; look for high workflow_task_schedule_to_start_latency when load grows.

Escalation Checklist

  • Capture logs

    Attach Compozy and Temporal logs when filing an issue.

  • Record configuration

    Include temporal and standalone sections of compozy.yaml and any CLI overrides you used.

  • Note versions

    Provide the Compozy version, Go runtime version, and Temporal server version if running remotely.

Temporal Modes
Decide when to use remote or standalone
Embedded Temporal
Understand how standalone services are composed
compozy start CLI
CLI flags for Temporal connectivity

Database Troubleshooting

Resolve PostgreSQL and SQLite issues, from connection failures to vector database configuration.

Common Issues

Frequent problems and quick resolutions for standalone and distributed modes.