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 unsuccessful, 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>

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 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

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 de deploy or git push plotly main.

send-pack: unexpected disconnect while reading sideband packet

Connection to gitea-ssh.plotly-system.svc.cluster.local closed by remote host.
2024/01/24 23:02:19 exit status 255
send-pack: unexpected disconnect while reading sideband packet
fatal: the remote end hung up unexpectedly

This error occurs when you are trying to push large files using the Dash Enterprise CLI < 1.7.0 or Git commands over HTTPS.

To resolve, you have three options:

and then retry the deployment.

Failed to find attribute ‘server’ in ‘app’

de deploy / 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.

It looks like you are missing a Procfile in this directory

de deploy fails with

It looks like you are missing a Procfile in this directory, which is required for deployment.

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

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.

It looks like you are missing a requirements.txt in this directory

de deploy fails with

It looks like you are missing a requirements.txt in this directory, which is required for deployment.

This error occurs when your app doesn’t have a requirements.txt file. If you are deploying a Conda app and have included an environment.yml file, proceed with the deployment by pressing y at the prompt.

Dash Enterprise detects requirements.txt (pip) and environment.yml (Conda) files to select the buildpack and build your app. See App Structure
for more details.

requirements.txt or environment.yml not detected

de deploy / 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

de deploy / 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

de deploy / 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://&lt;your-dash-enterprise-server&gt;/GIT/&lt;your-dash-app&gt;/

$ git push plotly main
[...]
fatal: Authentication failed for 'https://&lt;your-dash-enterprise-server&gt;/GIT/&lt;your-dash-app&gt;/'

This error can occur when your administrator has configured Dash Enterprise authentication to
use SAML or OIDC and you are trying to deploy changes using Git commands over HTTPS. When Dash Enterprise
is configured with SAML or OIDC, HTTPS deployments are not supported.

To resolve, you have two options: * Deploy using the Dash Enterprise CLI. The Dash Enterprise CLI uses HTTPS, but is not subject to this authentication limitation. * Set up SSH keys and deploy over SSH.

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 &lt;your-username&gt; does not have permissions to run git-hook on &lt;your-dash-app&gt;, or &lt;your-dash-app&gt; does not exist
remote: Access denied
To &lt;your-dash-enterprise-server&gt;/GIT/&lt;your-dash-app&gt;
! [remote rejected] main -> main (pre-receive hook declined)

error: failed to push some refs to '&lt;your-dash-enterprise-server&gt;:&lt;your-dash-app&gt;'

$ git push plotly main
[...]
ssh: connect to host &lt;your-dash-enterprise-server&gt; 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 using Git commands 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:&lt;your-dash-app&gt;@//&lt;your-dash-enterprise-server&gt;/GIT/&lt;your-dash-app&gt;
Cloning into '&lt;your-dash-app&gt;'...
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://&lt;your-dash-enterprise-server&gt;/GIT/&lt;your-dash-app&gt;.

pip subprocess to install build dependencies did not run successfully

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

   × pip subprocess to install build dependencies did not run successfully.
   │ exit code: 1
   ╰─> [13 lines of output]
       Looking in links: /layers/paketo-buildpacks_pip/pip-source
       Processing /layers/paketo-buildpacks_pip/pip-source/setuptools-69.0.2.tar.gz
         Getting requirements to build wheel: started
         Getting requirements to build wheel: finished with status 'done'
         Installing backend dependencies: started
         Installing backend dependencies: finished with status 'done'
         Preparing metadata (pyproject.toml): started
         Preparing metadata (pyproject.toml): finished with status 'done'
       Collecting wheel
         Using cached wheel-0.42.0-py3-none-any.whl
       INFO: pip is looking at multiple versions of &lt;Python&gt; to determine which version is compatible with other requirements. This could take a while.
       INFO: pip is looking at multiple versions of wheel to determine which version is compatible with other requirements. This could take a while.
       ERROR: Package 'setuptools' requires a different Python: 3.7.16 not in '>=3.8'
       [end of output]

   note: This error originates from a subprocess, and is likely not a problem with pip.
 error: subprocess-exited-with-error
 × pip subprocess to install build dependencies did not run successfully.
 │ exit code: 1
 ╰─> See above for output.
 note: This error originates from a subprocess, and is likely not a problem with pip.
 error: exit status 1
 Timer: Builder ran for 9.463674366s and ended at 2025-02-28T19:39:17Z
 ERROR: failed to build: exit status 1

This error occurs when your app tries to use Python 3.7 with a version of pip that is not compatible.

To resolve, you have two options:

gunicorn: error: unrecognized arguments

de deploy / 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

de deploy / 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.

Memory Over the Limit

Deployment fails and 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.

Licensed Memory Over the Limit

Deployment is successful, but your app’s web process is in Stopped status with licensed_memory_over_the_limit. Additionally, an error banner is displayed.

<img>

This error occurs when the resources on Dash Enterprise consume more memory than is allowed by the memory limit defined in the Dash Enterprise license. Contact your administrator so that they can re-evaluate the licensed memory limit.

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.