> For the complete documentation index, see [llms.txt](https://docs.portainer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.portainer.io/portainer-idp/using-portainer-idp/troubleshooting.md).

# Troubleshooting

## When a deployment fails

When a deployment fails on an environment, the failed row on the application's **Environments** tab explains the error in plain language and says what to do. Portainer's original message is under **Details**. Common causes are:

* An image that can't be pulled. For a private registry, add [registry credentials](https://docs.portainer.io/portainer-idp/using-portainer-idp/secrets.md#registry-credentials) and choose them as the **Image pull secret**.
* A missing namespace.
* A quota or admission policy rejecting the manifest.
* An environment whose Edge Agent isn't connected.

## Common messages

<details>

<summary>Finish setting up</summary>

Portainer-IDP has no Edge Admin credential yet. An administrator needs to set it up on [Settings](https://docs.portainer.io/portainer-idp/using-portainer-idp/admin/settings.md#edge-admin-credential).

</details>

<details>

<summary>Access required</summary>

Portainer-IDP's Edge Admin credential is missing, no longer valid, or lacks the Edge Administrator role. An administrator can check it on [Settings](https://docs.portainer.io/portainer-idp/using-portainer-idp/admin/settings.md) with **Test credential**, and replace it with **Rotate credentials**.

</details>

<details>

<summary>Cannot reach Portainer</summary>

The add-on can't connect to Portainer, or Portainer refused its certificate or machine credential. Repairing the add-on in Portainer issues a fresh credential.

</details>

<details>

<summary>Edge Compute is disabled</summary>

Portainer-IDP deploys through Portainer's Edge features. An administrator needs to enable Edge Compute in Portainer's settings.

</details>

<details>

<summary>Portainer lost its copy of the file</summary>

Choose **Redeploy** on the failed row, on the application's **Environments** tab or a secret's **Placement** tab, to pull the file from Git again.

</details>

<details>

<summary>Sealed Secrets is not ready on every environment</summary>

One or more environments the secret is going to can't decrypt it. An administrator can install or repair Sealed Secrets from [Cluster Readiness](https://docs.portainer.io/portainer-idp/using-portainer-idp/admin/cluster-readiness.md#sealed-secrets), or directly from the message.

</details>

<details>

<summary>Your saved token can no longer be read</summary>

The encryption key changed. Enter your token again on [Git commit identity](https://docs.portainer.io/portainer-idp/using-portainer-idp/git-commit-identity.md).

</details>

<details>

<summary>Refused by the Helm policy</summary>

The chart, with your values, creates something the Helm policy doesn't allow. The review step lists each rule it breaks. See [The Helm policy](https://docs.portainer.io/portainer-idp/using-portainer-idp/deploy.md#the-helm-policy).

</details>

<details>

<summary>This application was changed since you opened it</summary>

Someone else saved a change to the file after you opened it, and saving yours would have undone it. Reload to see the latest, then reapply your changes.

</details>

<details>

<summary>A namespace is already declared by another deploy target</summary>

Two deploy targets can't declare the same namespace on one environment, because they'd share one Kubernetes namespace and removing it from either would delete it for both. Choose another name, or leave the shared environments out. See [Deploy targets](https://docs.portainer.io/portainer-idp/using-portainer-idp/deploy-targets.md#creating-a-deploy-target).

</details>

<details>

<summary>Enter a host for the Ingress</summary>

Portainer-IDP refuses an Ingress with no host, because it would take every request that no other application claims. Enter a host, or expose the application as a NodePort or not at all. See [What Portainer-IDP refuses](https://docs.portainer.io/portainer-idp/using-portainer-idp/deploy.md#what-portainer-idp-refuses).

</details>

<details>

<summary>A namespace or deploy target is missing from a deploy form</summary>

You don't have access to it. Ask an administrator to add you under **Who may use it** on the namespace.

</details>

<details>

<summary>A button is disabled</summary>

Hover over it. The tooltip says why, usually because your [role](https://docs.portainer.io/portainer-idp/architecture/roles.md) doesn't allow that action.

</details>

## FAQ

<details>

<summary>Do developers need Portainer edge rights?</summary>

No. Portainer-IDP deploys with its own Edge Admin credential and checks access itself. Developers need a Portainer account, an environment role that gives them the right Portainer-IDP role, and access to a deploy target and namespace.

</details>

<details>

<summary>Can I edit the manifests in Git directly?</summary>

Yes. Changes made in Portainer-IDP are commits to the same file, so the two stay in step. Whether, and how often, Portainer checks the repository for changes is set on the Git repository's GitOps source in Portainer.

</details>

<details>

<summary>Why do I need a personal access token?</summary>

Commits are made as you, with your token, so Git history shows who changed what. Portainer's own credential on the Git repository is only used to read.

</details>

<details>

<summary>Can I deploy to Docker environments?</summary>

No. Deploy targets contain Kubernetes environments connected with the Edge Agent only.

</details>

<details>

<summary>Are secret values stored in Git?</summary>

Only encrypted, as Sealed Secrets. Values are encrypted in your browser before they're committed, and only the clusters you deploy to can decrypt them.

</details>

<details>

<summary>What happens to my applications if I remove Portainer-IDP?</summary>

They keep running. The manifests stay in Git and the Edge Stacks stay in Portainer.

</details>
