Troubleshooting App Deployment Errors

This documentation is for Dash Enterprise.
Dash Enterprise is the fastest way to write & deploy Dash apps and
Jupyter notebooks.
10% of the Fortune 500 uses Dash Enterprise to productionize AI and
data science apps. Find out if your company is using Dash Enterprise.

This troubleshooting guide describes errors that you may encounter when deploying apps to Dash Enterprise as well as steps to resolve them. It can help you if you ran a Git command that was unsuccesful, or if the Overview of your app in the
App Info displays “Build failed” or “Deployment failed”.

Troubleshooting Checklist

Common Errors

error: failed to push some refs to git@<dash-enterprise>:<app-name>

$ git push plotly main
[...]
To <your-dash-enterprise-server>:<your-dash-app>
! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to '<your-dash-enterprise-host>:<your-dash-app>'

This is a generic error message that indicates that the git push failed. Look for a different error message further up in the logs and search for that error on this page.


remote contains work that you do not have locally

$ git push plotly main
To <your-dash-enterprise-server>/GIT/<your-dash-app>
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to '<your-dash-enterprise-server>/GIT/<your-dash-app>'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

This error occurs when the version of your app that is deployed to Dash Enterprise is ahead of what you have on your workstation. For example, if you use a shared GitHub repository to manage your app code, a colleague
may have made a change and pushed it to Dash Enterprise. Use a command like git pull origin main to get your colleague’s work locally before pushing your own changes to Dash Enterprise with git push plotly main.


Procfile not found

git push plotly main is successful, but the build fails and your build logs display

---> DEPLOYMENT SCRIPTS
Procfile not found. Please update your app and retry!
ERROR: failed to build: exit status 1

This error occurs when your app doesn’t contain a Procfile. See App Structure
for more details on Procfile.


Failed to find attribute ‘server’ in ‘app’

git push plotly main is successful, but the deployment fails and your app logs display

[2022-11-10 01:35:53 +0000] [18] [INFO] Worker exiting (pid: 18)
[2022-11-10 01:35:53 +0000] [21] [INFO] Worker exiting (pid: 21)
Failed to find attribute 'server' in 'app'.Failed to find attribute 'server' in 'app'.

This error occurs when server = app.server is missing from the entry point to your app (usually app.py).

The line server = app.server is required to define the server variable so that it can be exposed for the Procfile. See App Structure
for more details.


requirements.txt or environment.yml not detected

git push plotly main is successful, but the build fails and your build logs display

---> DEPLOYMENT SCRIPTS
requirements.txt or environment.yml not detected. Dash Enterprise only supports Python and Conda apps! Exiting..
ERROR: failed to build: exit status 1

This error occurs when your app doesn’t have a requirements.txt (pip) or environment.yml (Conda) file. Dash Enterprise
detects these files to select the buildpack and build your app. See App Structure
for more details.


bash: gunicorn: command not found

git push plotly main is successful, but the deployment fails and your app logs display

[2022-11-10 00:41:09 +0000] [1] [INFO] Handling signal: term
[2022-11-10 00:41:09 +0000] [18] [INFO] Worker exiting (pid: 18)
[2022-11-10 00:41:09 +0000] [21] [INFO] Worker exiting (pid: 21)
[2022-11-10 00:41:09 +0000] [19] [INFO] Worker exiting (pid: 19)
[2022-11-10 00:41:09 +0000] [20] [INFO] Worker exiting (pid: 20)
[2022-11-10 00:41:10 +0000] [1] [INFO] Shutting down: Master
bash: gunicorn: command not found
bash: gunicorn: command not found
bash: gunicorn: command not found
bash: gunicorn: command not found

This error occurs when gunicorn is missing from your app’s requirements.txt file. See App Structure
for more details on gunicorn and requirements.txt.


Could not find a version that satisfies the requirement

git push plotly main is successful, but the build fails and your build logs display something similar to

pip install failed:
ERROR: Could not find a version that satisfies the requirement dash==26.2 (from versions: 0.17.4, 0.17.5, 0.17.7, 0.17.8rc1, 0.17.8rc2, 0.17.8rc3, 0.18.0, 0.18.1, 0.18.2, 0.18.3rc1, 0.18.3, 0.19.0, 0.20.0, 0.21.0, 0.21.1, 0.22.0rc1, 0.22.0rc2, 0.22.0, 0.23.1, 0.24.0, 0.24.1rc1, 0.24.1, 0.24.2, 0.25.0, 0.25.1, 0.26.0, 0.26.1rc1, 0.26.1rc2, 0.26.1rc3, 0.26.1, 0.26.2, 0.26.3, 0.26.4, 0.26.5, 0.26.6, 0.27.0rc1, 0.27.0rc2, 0.27.0rc3, 0.27.0rc4, 0.27.0rc5, 0.27.0rc6, 0.27.0rc7, 0.27.0rc8, 0.27.0rc9, 0.27.0, 0.28.0, 0.28.1, 0.28.2, 0.28.3, 0.28.4, 0.28.5, 0.28.6, 0.28.7, 0.29.0rc1, 0.29.0rc2, 0.29.0rc3, 0.29.0rc4, 0.29.0rc5, 0.29.0rc6, 0.29rc7, 0.29.0rc8, 0.29.0, 0.30.0rc1, 0.30.0rc2, 0.30.0rc3, 0.30.0rc4, 0.30.0rc5, 0.30.0, 0.31.0rc1, 0.31.0rc2, 0.31.0, 0.31.1, 0.32.0rc1, 0.32.0rc2, 0.32.0, 0.32.1, 0.32.2, 0.34.0, 0.35.0rc1, 0.35.0, 0.35.1, 0.35.2, 0.35.3, 0.36.0rc1, 0.36.0, 0.37.0rc1, 0.37.0rc2, 0.37.0, 0.38.0rc1, 0.38.0, 0.39.0, 0.40.0rc1, 0.40.0, 0.41.0, 0.42.0, 0.43.0rc1, 0.43.0rc2, 0.43.0rc3, 0.43.0, 1.0.0a1, 1.0.0, 1.0.1rc1, 1.0.1, 1.0.2, 1.1.0, 1.1.1, 1.2.0, 1.3.0, 1.3.1, 1.4.0, 1.4.1, 1.5.0, 1.5.1, 1.6.0, 1.6.1, 1.7.0, 1.8.0, 1.9.0, 1.9.1, 1.10.0, 1.11.0, 1.12.0, 1.13.0, 1.13.1, 1.13.2, 1.13.3, 1.13.4, 1.14.0, 1.15.0, 1.16.0, 1.16.1, 1.16.2, 1.16.3, 1.17.0, 1.18.0, 1.18.1, 1.19.0, 1.20.0, 1.21.0, 2.0.0rc1, 2.0.0rc2, 2.0.0rc3, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.3.1, 2.4.0, 2.4.1, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0)
ERROR: No matching distribution found for dash==26.2

error: exit status 1
ERROR: failed to build: exit status 1

This error can occur if there is a problem in
your requirements.txt file. To resolve, check the versioning in your
requirements.txt file. In the example above, the error occurred because
dash==26.2 is not a version of Dash.

If you’re working in a virtual environment,
you can check your package versions with:

$ pip list

if something in the list differs from your requirements.txt, you can update your requirements.txt with:

pip freeze > requirements.txt

See App Structure for more details on requirements.txt.


fatal: Authentication failed for https://<your-dash-enterprise-server>/GIT/<your-dash-app>/

$ git push plotly main
[...]
fatal: Authentication failed for 'https://<your-dash-enterprise-server>/GIT/<your-dash-app>/'

This error can occur when your administrator has configured Dash Enterprise authentication to
use SAML or OIDC and you are trying to deploy changes over HTTPS. When Dash Enterprise
is configured with SAML or OIDC, HTTPS deployments are not supported.
Resolve this by adding an SSH remote and deploying over SSH.

This error can also occur when you try to git clone an app that you own or co-own over HTTPS in a workspace. This is a known issue. To work around this
issue, you can delete the contents of the ~/.gitconfig file, then run git clone again and supply your Dash Enterprise credentials when prompted.


remote: Access denied

$ git push plotly main
[...]
Counting objects: 3, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 5.18 KiB | 2.59 MiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)

remote: User <your-username> does not have permissions to run git-hook on <your-dash-app>, or <your-dash-app> does not exist
remote: Access denied
To <your-dash-enterprise-server>/GIT/<your-dash-app>
! [remote rejected] main -> main (pre-receive hook declined)

error: failed to push some refs to '<your-dash-enterprise-server>:<your-dash-app>'
$ git push plotly main
[...]
ssh: connect to host <your-dash-enterprise-server> port 22: Connection timed out

fatal: Could not read from remote repository.

Please make sure you have the correct access rights

and the repository exists.

If deploying over HTTPS, then this can occur if your username or password is incorrect. Note that usernames and passwords in Dash Enterprise are case sensitive; e.g. the username Chris.Parmer is different than the username chris.parmer.

Git can sometimes cache these usernames after you’ve typed them. Run git config credential.helper to verify and correct the username.

Also, some operating system’s password managers can cache usernames as well. Open your operating system’s password manager and verify the username and password if you are deploying with https, running into access denied errors, and Git isn’t asking you for your username and password.


Please make sure you have the correct access rights and the repository exists

$ git clone https:<your-dash-app>@//<your-dash-enterprise-server>/GIT/<your-dash-app>
Cloning into '<your-dash-app>'...
ssh: Could not resolve hostname https: Name or service not known
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

This error can occur if there is an error in the repository URL. In the example above, the
repository to be cloned over HTTPS should look like https://<your-dash-enterprise-server>/GIT/<your-dash-app>.


gunicorn: error: unrecognized arguments

git push plotly main is successful, but the deployment fails and your app logs display

[2022-11-10 00:41:09 +0000] [1] [INFO] Handling signal: term
[2022-11-10 00:41:09 +0000] [18] [INFO] Worker exiting (pid: 18)
[2022-11-10 00:41:09 +0000] [21] [INFO] Worker exiting (pid: 21)
[2022-11-10 00:41:09 +0000] [19] [INFO] Worker exiting (pid: 19)
[2022-11-10 00:41:09 +0000] [20] [INFO] Worker exiting (pid: 20)
[2022-11-10 00:41:10 +0000] [1] [INFO] Shutting down: Master
usage: gunicorn [OPTIONS] [APP_MODULE]
gunicorn: error: unrecognized arguments: --timout 2
usage: gunicorn [OPTIONS] [APP_MODULE]
gunicorn: error: unrecognized arguments: --timout 2
usage: gunicorn [OPTIONS] [APP_MODULE]
gunicorn: error: unrecognized arguments: --timout 2
usage: gunicorn [OPTIONS] [APP_MODULE]
gunicorn: error: unrecognized arguments: --timout 2

This error occurs when the web process defined in your Procfile has an invalid argument. In the example above, “timeout” is spelled incorrectly.

To resolve, verify the format and spelling of those arguments. See Gunicorn Docs on Settings for more details.


[CRITICAL] WORKER TIMEOUT

git push plotly main is successful, but the deployment fails and your app logs display something similar to

[2022-11-10 16:25:20 +0000] [4786] [INFO] Booting worker with pid: 4786
[2022-11-10 16:25:20 +0000] [4787] [INFO] Booting worker with pid: 4787
[2022-11-10 16:25:52 +0000] [1] [CRITICAL] WORKER TIMEOUT (pid:4770)
[2022-11-10 16:25:52 +0000] [1] [CRITICAL] WORKER TIMEOUT (pid:4771)
[2022-11-10 16:25:52 +0000] [4770] [INFO] Worker exiting (pid: 4770)
[2022-11-10 16:25:52 +0000] [4771] [INFO] Worker exiting (pid: 4771)
[2022-11-10 16:25:52 +0000] [4851] [INFO] Booting worker with pid: 4851
[2022-11-10 16:25:52 +0000] [4852] [INFO] Booting worker with pid: 4852
[2022-11-10 16:25:53 +0000] [1] [CRITICAL] WORKER TIMEOUT (pid:4786)
[2022-11-10 16:25:53 +0000] [1] [CRITICAL] WORKER TIMEOUT (pid:4787)
[2022-11-10 16:25:53 +0000] [4786] [INFO] Worker exiting (pid: 4786)
[2022-11-10 16:25:53 +0000] [4787] [INFO] Worker exiting (pid: 4787)

This can happen in the following scenarios:

In this scenario, the gunicorn web process does not have enough
time to complete its task during the booting process. By default,
gunicorn has a 30 second timeout. Workers silent for more than this
many seconds are killed and restarted.

To resolve, we recommend that you first use the --preload flag to reduce your
app’s memory consumption and speed up boot time. Avoid the --preload
flag if you are using shared database connection pools. See
Gunicorn docs on preloading
for more details.

```
web: gunicorn app:server –workers 4 –preload

```

Use the --timeout flag only if you cannot use the --preload flag.
--timeout allows you to modify the default amount of time available
for your workers to complete a task. See
Gunicorn docs on timeout
for details.

```
web: gunicorn app:server –workers 4 –timeout 90

```

To resolve, consider using Background Callbacks.


App Builds but Deployment Stays Pending

git push plotly main is successful and the build completes, but the App Info displays a “Deployment Pending” status that does not progress.

<img>

This occurs when there is no Python file at the root of your app.

To resolve, you have two options:


Memory Over the Limit

git push plotly main is successful, but your app’s web process is in Stopped status with memory_over_the_limit.

<img>

Additionally, your app logs display something similar to

[2023-03-28 01:17:45 +0000] [1] [WARNING] Worker with pid 20 was terminated due to signal 9
[2023-03-28 01:17:45 +0000] [1] [INFO] Shutting down: Master

This error occurs when your app attempts to consume more memory than is allowed by its memory limit.

To resolve, you have two options:

Do not use the --preload flag if you are using shared database connection pools (see Database Connections). For more information on preloading, refer to the Gunicorn docs.
* Reducing the amount of workers defined in your Procfile.
* Using a file type for your dataset that supports memory mapping, like Arrow, and reading it with libraries like Vaex.
* Performing data queries and aggregations within the query on a database layer instead of in memory with Python. * Ask your administrator to increase your app’s memory limit. If they set a custom memory limit, your app is restarted. If your app uses the default memory limit and your administrator opts to instead increase this default, select Start <img> to restart your app.


fatal: Unable to create ‘.git/index.lock’: File exists

$ git add .
fatal: Unable to create '.git/index.lock': File exists.

Another git process seems to be running in this repository, e.g.
an editor opened by 'git commit'. Please make sure all processes
are terminated then try again. If it still fails, a git process
may have crashed in this repository earlier:
remove the file manually to continue.

This error can occur if you ran git commit -a in a different terminal. All Git commits create a .git/index.lock file temporarily, but the
git commit -a command does not terminate the Git process after doing so, preventing another process from creating the .git/index.lock file.

To resolve:

  1. Run ps aux or ps aux |grep git to list running processes.
  2. If you see a process with git commit -a as its COMMAND, make a note of its process ID (PID) and terminate it:
    ps kill &lt;process-ID&gt;
    where &lt;process-ID&gt; is the ID of the git commit -a process.
  3. If you don’t see a process corresponding to git commit -a, manually delete the .git/index.lock file:
    rm .git/index.lock

Commit your changes with git commit -m "commit message" to avoid this error in the future.