Troubleshoot from evidence, not guesses
Start with System health and the exact failing journey, then isolate configuration, infrastructure, provider, and application boundaries in that order.
First-response checklist
- Record scope. Note route, account role, model or gateway, timestamp, timezone, and the last successful attempt.
- Protect data. Do not clear records, retry financial events, or replace files until a backup and identifiers are captured.
- Read System health. Resolve red database, queue, scheduler, storage, mail, provider, license, or cache checks first.
- Inspect sanitized logs. Correlate the request or job ID and redact secrets before sharing.
- Reproduce once. Use the smallest safe test under the same environment; avoid creating a retry storm.
Installer and database errors
| Symptom | Checks |
|---|---|
| Installer token rejected | Use the token delivered with this package, preserve exact characters, verify time and session/cookie behavior, and request a new authorized token if expired. |
| Requirement check fails | Compare PHP CLI and web versions, enable the named extension, and restart the correct PHP-FPM/Apache service. |
| Database connection fails | Verify host, port, database, user, password, network allowance, TLS mode, and that credentials belong to this database. |
| Database is not empty | Use a new database for a new installation or follow the supported upgrade path; do not install over unknown tables. |
| Writable-path error | Grant the web/worker identity write access only to the listed storage and cache paths; do not make the entire project world-writable. |
| Application shows 500 | Check the protected application log, application key, environment parsing, database, cache path, PHP extensions, and file ownership. |
Jobs remain queued
- A supervised worker process is running under the intended PHP binary and project directory.
- The worker listens to
audioand every other configured queue, not onlydefault. - The queue connection and credentials match the web application.
- The scheduler has run within the expected interval.
- Workers were restarted after a deployment or environment change.
- The process timeout exceeds the application's job timeout and provider request window.
- The failed-job detail is inspected before a single controlled retry.
If credits were reserved, use the recorded job state and ledger idempotency key. Do not manually grant or remove credits until the application has reconciled the terminal state.
Provider and streaming errors
| Symptom | Resolution path |
|---|---|
| Connection test fails | Re-enter the current key, verify provider entitlement/quota and outbound HTTPS/DNS, then inspect the sanitized provider status. |
| Job submits but never progresses | Verify callbacks or polling, public HTTPS reachability, worker/scheduler health, provider status, and request identifiers. |
| No early audio | Confirm the chosen model/provider actually supplied a safe streaming URL. Audoryx must not label a failed or merely queued row as live. |
| Audio plays after completion only | The provider may not expose progressive audio for that request; completed playback remains valid behavior. |
| Lyrics do not synchronize | Confirm a normalized timed-lyrics payload exists. Plain text lyrics remain readable but cannot be highlighted by time. |
| Invalid provider response | Record provider/job IDs and sanitized response metadata; update the adapter only after comparing the provider's current official contract. |
Private media does not play
- Confirm the user is authorized for the track and the track record points to an existing private object.
- Check storage credentials, region/endpoint, clock synchronization, and signed URL lifetime.
- Inspect browser range requests and content type; audio seeking depends on correct byte-range behavior.
- Do not convert private storage to public as a shortcut.
Payment and webhook errors
- Confirm sandbox/live mode, currency, and external catalog identifiers belong to the same provider environment.
- Use the exact HTTPS webhook URL shown in Audoryx and the correct signing secret for that endpoint.
- Check provider delivery logs for response status and retry history.
- Verify server time and that a reverse proxy does not alter the raw body used for signature verification.
- Do not mark a payment complete from a browser success parameter; retrieve or accept the canonical provider event.
- Replay only through the provider's official tool and confirm idempotency prevents duplicate credits.
License and marketplace errors
| Message | What to check |
|---|---|
| No valid license | Sign in as administrator, open Licenses, synchronize, and verify public origin, certificate dates, server time, and EKR connectivity. |
| Origin mismatch | Use the canonical final HTTPS host. Release the old binding through the legitimate move flow before activating another origin. |
| No themes available | Synchronize license and marketplace, confirm account ownership, product compatibility, catalog availability, and EKR status. |
| Theme update refused | Check semantic version increase, package identifier, manifest v3 schema, Audoryx compatibility, archive paths, and declared assets. |
| Preview button absent | The marketplace product must have a validated HTTPS preview URL configured by its publisher. |
Theme or responsive layout problems
- Return to the permanent default theme to determine whether the issue is package-specific.
- Clear application/browser caches after a verified package update, then hard refresh once.
- Check the active theme, locale direction, viewport, zoom, reduced motion, and long-string content.
- Validate the package against manifest v3 schema and ensure CSS stays scoped.
- Report the exact page, viewport, theme version, locale, and screenshot with sensitive data redacted.
An update fails
Leave maintenance enabled while the updater restores the recorded files and database. Do not manually merge the failed archive into production. Review the update audit ID, preflight failure or exception, rollback result, disk space, permissions, package digest, PHP version, and database engine. Escalate with a sanitized support bundle if recovery is not confirmed.
Escalate safely
Include version, hostname without credentials, PHP/database versions, active theme, exact steps, expected/actual result, timestamps, correlation IDs, health summary, and a minimal redacted log excerpt. Never send an environment file, application key, API key, password, purchase code, bearer token, cookie, signature, private media URL, or full payment payload.