{"result":{"depiction_url":null,"edges":{"hasreference":{"objects":[{"created":"2026-10-07T11:13:50Z","object_id":{"id":2997,"is_a":["text","documentation","developerguide"],"name":"developer_site_not_starting","title":{"_type":"trans","tr":{"en":"A site does not start"}},"uri":"https:\/\/zotonic.com\/id\/2997"},"seq":1},{"created":"2026-10-07T11:13:50Z","object_id":{"id":3070,"is_a":["text","documentation","adminguide"],"name":"admin_database_connection","title":{"_type":"trans","tr":{"en":"Check or change a site database connection"}},"uri":"https:\/\/zotonic.com\/id\/3070"},"seq":2},{"created":"2026-10-07T11:13:50Z","object_id":{"id":3066,"is_a":["text","documentation","adminguide"],"name":"admin_hostnames_https","title":{"_type":"trans","tr":{"en":"Configure hostnames and HTTPS"}},"uri":"https:\/\/zotonic.com\/id\/3066"},"seq":3}],"predicate":{"id":2774,"is_a":["meta","predicate"],"name":"hasreference","title":{"_type":"trans","tr":{"en":"Documentation reference"}},"uri":"https:\/\/zotonic.com\/id\/hasreference"}},"references":{"objects":[{"created":"2020-05-30T05:48:04Z","object_id":{"id":1279,"is_a":["text","documentation"],"name":"doc_glossary","title":"Glossary","uri":"https:\/\/zotonic.com\/id\/1279"},"seq":1000000},{"created":"2020-05-30T05:48:04Z","object_id":{"id":1319,"is_a":["text","documentation","developerguide"],"name":"doc_developerguide_deployment_server_configuration","title":{"_type":"trans","tr":{"en":"Tune server limits from measured load"}},"uri":"https:\/\/zotonic.com\/id\/1319"},"seq":1000000}],"predicate":{"id":332,"is_a":["meta","predicate"],"name":"references","title":{"_type":"trans","tr":{"en":"References"}},"uri":"https:\/\/zotonic.com\/id\/references"}},"subject":{"objects":[{"created":"2026-10-07T11:13:50Z","object_id":{"id":2558,"is_a":["categorization","keyword","keyword_information_type"],"name":"zotonic_topic_troubleshooting","title":"Troubleshooting","uri":"https:\/\/zotonic.com\/id\/2558"},"seq":1},{"created":"2026-10-07T11:13:50Z","object_id":{"id":2564,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_backend_developer","title":"Backend developer","uri":"https:\/\/zotonic.com\/id\/2564"},"seq":2},{"created":"2026-10-07T11:13:50Z","object_id":{"id":2613,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_development_and_debugging","title":"Development and debugging","uri":"https:\/\/zotonic.com\/id\/2613"},"seq":3},{"created":"2026-10-07T11:13:50Z","object_id":{"id":2605,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_site_management","title":"Site management","uri":"https:\/\/zotonic.com\/id\/2605"},"seq":4}],"predicate":{"id":308,"is_a":["meta","predicate"],"name":"subject","title":{"_type":"trans","tr":{"en":"Keyword"}},"uri":"http:\/\/purl.org\/dc\/elements\/1.1\/subject"}}},"id":1529,"is_a":["text","documentation","developerguide"],"links":[{"rel":"self","target":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/1529"},{"rel":"hub","target":"https:\/\/zotonic.com\/.zotonic\/websub"}],"medium":null,"medium_url":null,"name":"doc_developerguide_troubleshooting","page_url":{"en":"https:\/\/zotonic.com\/docs\/1529\/a-site-does-not-start","x-default":"https:\/\/zotonic.com\/docs\/1529\/a-site-does-not-start"},"preview_url":null,"resource":{"body":{"_type":"trans","tr":{"en":"

Run bin\/zotonic status<\/code> to distinguish an unavailable node from a stopped or failing site. Inspect the relevant startup log before repeatedly restarting it.<\/p>\n

For a site failure, check configuration parsing, database access, required applications, and module initialization. Use siteconfigfiles<\/code> to confirm which configuration files were selected. Do not paste credentials from configuration output into an issue.<\/p>\n

Fix the first reported cause, start the site again, and verify an HTTP response. Later errors may be consequences of the first startup failure.<\/p>\n

Check or change a site database connection<\/h2>\n

Access needed:<\/strong> Database and server configuration access.<\/p>\n

  1. Identify the site's effective database host, port, database name, role, and schema. Do not print the password into a shared report.<\/li>
  2. Test connectivity from the same host or container that runs Zotonic. A successful connection from your laptop may follow a different route.<\/li>
  3. Check authentication and the role's access to the intended database and schema.<\/li>
  4. Make a required connection change in acceptance first, at the owning configuration layer.<\/li>
  5. Restart or reload according to the deployment procedure and check startup logs.<\/li>
  6. Verify an existing page and a small write using the intended site account. Confirm that you did not connect to an empty or wrong environment's database.<\/li><\/ol>\n

    A schema separates site tables within a database; it is not a substitute for environment isolation. Do not grant superuser rights to bypass a permissions error. For a fresh local development database, use the developer setup task instead of adapting production credentials.<\/p>\n

    Local socket connections<\/h2>\n

    For PostgreSQL on the same host, set dbhost<\/code> to socket<\/code> (atom, string, or binary) to use \/run\/postgresql<\/code>, or set it to an absolute socket directory. dbport<\/code> selects .s.PGSQL.<port><\/code>, normally .s.PGSQL.5432<\/code>. This mode does not fall back to TCP.<\/p>\n

    Check SHOW unix_socket_directories;<\/code> in PostgreSQL and test with psql -h \/run\/postgresql -p 5432 -U ROLE -d DATABASE<\/code> as the Zotonic service user. Socket connections use local<\/code> rules in pg_hba.conf<\/code>; TCP connections use host<\/code> rules. Match the intended password or peer-authentication policy. Keep the socket directory writable only by trusted users. For containers, verify the mount and permissions inside the container.<\/p>\n

    Configure hostnames and HTTPS<\/h2>\n

    Access needed:<\/strong> DNS and server configuration access.<\/p>\n

    1. Decide the canonical hostname and required aliases. Make DNS point to the intended server or reverse proxy.<\/li>
    2. Set the matching site hostname and aliases, and check the externally visible HTTP\/HTTPS ports.<\/li>
    3. Choose where TLS terminates: Zotonic or a reverse proxy. Install certificates through that component's supported mechanism.<\/li>
    4. If using a proxy, forward the expected host and protocol information and support WebSocket connections. Keep direct backend access consistent with the deployment's access policy.<\/li>
    5. Test the canonical URL and each alias, redirects, certificate hostname and chain, admin login, and a live browser interaction.<\/li>
    6. Check certificate renewal and monitor expiry before it becomes an outage.<\/li><\/ol>\n

      A working DNS record does not select the correct Zotonic site unless the hostname matches its configuration. A certificate working in your own browser is not proof that public clients trust it.<\/p>\n

      For a local first run, use the developer setup instructions. Production certificates, public redirects, and proxy settings need the actual deployment's reviewed configuration.<\/p>"}},"category_id":{"id":317,"is_a":["meta","category"],"name":"developerguide","title":"Developer guide","uri":"https:\/\/zotonic.com\/id\/developerguide"},"content_group_id":{"id":339,"is_a":["meta","content_group"],"name":"default_content_group","title":{"_type":"trans","tr":{"en":"Default Content Group"}},"uri":"https:\/\/zotonic.com\/id\/default_content_group"},"created":"2020-05-30T05:47:24Z","creator_id":{"id":336,"is_a":["person","robot"],"name":"gitbot","title":"Git","uri":"https:\/\/zotonic.com\/id\/336"},"doc_editorial_bundle":true,"doc_editorial_edges":{"hasreference":[2997,3066,3070],"subject":[2558,2564,2605,2613]},"github_url":"https:\/\/github.com\/zotonic\/zotonic\/tree\/master\/doc\/developer-guide\/troubleshooting.rst","is_authoritative":true,"is_dependent":false,"is_featured":false,"is_protected":false,"is_published":true,"is_unfindable":false,"language":["en"],"modified":"2026-10-07T11:14:04Z","modifier_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"name":"doc_developerguide_troubleshooting","pivot_geocode":null,"pivot_location_lat":null,"pivot_location_lng":null,"privacy":0,"publication_end":"9999-06-01T00:00:00Z","publication_start":"2022-02-15T10:01:27Z","slug":"a-site-does-not-start","summary":{"_type":"trans","tr":{"en":"Run bin\/zotonic status to distinguish an unavailable node from a stopped or failing site. Inspect the relevant startup log before repeatedly restarting it."}},"title":{"_type":"trans","tr":{"en":"A site does not start"}},"title_slug":{"_type":"trans","tr":{"en":"a-site-does-not-start"}},"tz":"UTC","uri":null,"version":35,"visible_for":0},"uri":"https:\/\/zotonic.com\/id\/1529","uri_template":"https:\/\/zotonic.com\/id\/:id","websub":{"hub":"https:\/\/zotonic.com\/.zotonic\/websub","topic":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/1529"}},"status":"ok"}