Troubleshooting¶

Summary¶

Use this guide when SkyCMS setup, publishing, or runtime behavior fails unexpectedly.

Outcome¶

After using this guide, you should be able to identify the failing layer, run the most relevant diagnostic checks, and gather the right escalation details if the issue is not resolved immediately.

The fastest diagnosis pattern is layer-by-layer:

Database
Storage
CDN/cache
Publishing pipeline
Authentication/permissions
Runtime/container platform

Quick triage flow¶

flowchart TD
  Start[Issue observed] --> Category{Where does it fail?}
  Category --> DB[Database]
  Category --> Storage[Storage]
  Category --> CDN[CDN or cache]
  Category --> Publish[Publishing workflow]
  Category --> Auth[Auth or permissions]
  Category --> Runtime[Runtime or container]
  DB --> Verify[Verify credentials, connectivity, permissions]
  Storage --> Verify
  CDN --> Verify
  Publish --> Verify
  Auth --> Verify
  Runtime --> Verify
  Verify --> Resolve[Apply fix and re-test]

Most common root causes¶

Incorrect connection strings or secret values.
Missing provider permissions or IAM roles.
Firewall/network restrictions.
Publishing worker downtime.
Cache invalidation delay after publish.

Database issues¶

Database symptoms¶

"Cannot connect to database"
"Login failed" or "Access denied"
setup wizard cannot validate database step

Database checks¶

Confirm provider-specific connection string format.
Confirm network/firewall access from runtime host.
Confirm credential validity and database permissions.
Confirm target database exists and is reachable.

Database references¶

Storage issues¶

Storage symptoms¶

file upload fails
publish succeeds but asset writes fail
setup wizard storage validation fails

Storage checks¶

Verify storage account/bucket/container exists.
Verify read/write/delete permissions for configured identity.
Validate credentials using provider CLI tools.
Check region/network allowlists.

Storage references¶

CDN and cache issues¶

CDN symptoms¶

publish appears successful but site still shows old content
purge/invalidation errors in logs

Key point¶

CDN purge failures usually do not block publication to storage. They delay freshness at edge nodes.

CDN checks¶

Confirm CDN credentials and zone/distribution identifiers.
Re-run purge/invalidation for affected paths.
Validate cache TTL behavior.
Confirm origin content is updated before debugging CDN edge state.

Publishing workflow issues¶

Publishing symptoms¶

publish action fails
scheduled publish does not run
template update produces unexpected output

Publishing checks¶

Confirm publishing service/worker is running.
Confirm storage target is writable.
Confirm page/template permissions for acting user.
Reproduce with one minimal page to isolate workflow from content complexity.

Publishing references¶

Authentication and permission issues¶

Authentication symptoms¶

login fails for known user
editor actions unavailable despite expected role

Authentication checks¶

Verify user exists and is active.
Verify role assignment for required action.
Verify identity backend connectivity.
Reset credential or rotate secret if authentication backend changed.

Runtime and container issues¶

Runtime symptoms¶

app fails to start
setup URL unavailable
intermittent runtime crashes

Runtime checks¶

Confirm required environment variables are set.
Confirm port and host binding are valid.
Review container/runtime logs for startup exceptions.
Confirm volume mount paths and permissions.

Setup wizard specific issues¶

Wizard cannot proceed to review¶

Likely causes:

missing required values,
invalid storage/CDN credentials,
failed prior validation step.

Action:

Re-check each wizard step for success state.
Re-enter provider credentials.
Restart app and retry setup path.

Wizard not available after first run¶

Expected behavior: setup is disabled after successful completion.