How to debug Cloud deployment problems

Start with the debugging checklist. Work through the checklist by selecting the most appropriate answer for each question until you arrive at a probable fault for the symptoms you’re seeing.

There is also a complete decision tree for the debugging process.

Debugging checklist

Deployment on the Cloud has not worked as expected

Does the Control Panel show a “Last deployment failed” error message?

The Control Panel shows a Last deployment failed message

Open the log. The relevant section will be towards the end, so work backwards from the end. Any error will be clearly stated.

What does the deployment log contain?

Probable fault: temporary problem

Please try again. This is a rare and usually temporary problem. You may need to wait a few minutes for the condition to clear. If the issue is urgent, or you have already tried again, please contact Divio Support.

The deployment log contains no obvious error

Check the site’s runtime logs (via the Logs menu).

Do you see any obvious errors in the runtime logs for the web container (of the appropriate server, Test or Live)?

Probable fault: application is too slow to start and times out

Probably your application took so long to start up that it triggered a timeout condition. On our platform, if a site is not up and running within a certain period after its build has completed, then the deployment is marked as failed.

This could happen because it is waiting for another external resource to become available, or the processing it needs to do at start-up is excessive. These issues generally represent a programming problem that needs to be resolved.

Build the site locally and start up the application to investigate why it is taking so long.

If the start-up processes can’t be made faster or more lightweight, investigate an asynchronous processing option such as Celery to allow them to go on in the background while the project starts up.

Probable fault: programming error in runtime code

Probably the issue is a programming error in the site that takes down Django as it launches (typically, this will be an ImportError). The runtime log will reveal the error.

The deployment log contains an error

The end of the log will contain the key error.

What does the error most closely resemble?

Probable fault: dependency conflict

An error that starts:

Could not find a version that matches [...]

indicates that two or more of the components in your system have specified incompatible Python dependencies.

See How to identify and resolve a dependency conflict.

Probable fault: A Node error has halted the build

Example:

npm ERR! There is likely additional logging output above.
[0m[91m
[0m[91mnpm[0m[91m ERR![0m[91m Please include the following file with any support request:
[0m[91mnpm ERR! /npm-debug.log
[0m

In this case one of the Node component installation processes has failed. If the error is not clear from the log, contact Divio support for advice.

Probable fault: An import error halts one of the site build routines

Example:

Step 8/8 : RUN DJANGO_MODE=build python manage.py collectstatic --noinput
[...]
ImportError: No module named django_select2

In this case a Python application launched by an instruction in the Dockerfile has caused Django to halt with an error while it was trying to run the collectstatic command. This is a programming error. The traceback will show where it occurred.

Probable fault: temporary timeout error (read timeout)

Example:

ReadTimeoutError: [...] Read timed out.

This may occasionally occur when our deployment infrastructure is under heavy load. In most cases you can simply try again. If the issue is urgent, or you have already tried again, please contact Divio Support.

Probable fault: A runtime error

If you are not sure what the error message reveals, please contact Divio support for assistance.

Probable fault: programming error at runtime

Sometimes there is no failed deployment log, but the site fails to start. This is typically caused by a programming error that becomes apparent at runtime.

Usually, the browser will show a Django traceback, if the site is in DEBUG mode (this is the default for the Test server). Under some circumstances, it might not, but the error will be shown in the site’s runtime logs, available from the Logs menu in the Control Panel.