> For the complete documentation index, see [llms.txt](https://docs-v3.toucantoco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-v3.toucantoco.com/self-hosted-toucan/troubleshooting/bootstraping.md).

# Troubleshooting Bootstraping

This guide will help you debug common bootstraping issues.

Issues appearing here only happen on bootstrap. Other issues happening at runtime are not documented here.

## Post-install job is failing

The post-install job is failing.

The issue is a **configuration** issue, or a **network** issue.

### Detection

{% code title="bash" overflow="wrap" %}

```bash
kubectl get jobs --all-namespaces
```

{% endcode %}

With jobs looking like:

{% code title="Example" overflow="wrap" %}

```bash
NAMESPACE       NAME                              STATUS     COMPLETIONS   DURATION   AGE
<namespace>     toucan-stack-postinstall          Failed     0/1           1m         1d
```

{% endcode %}

### Possible causes

The post-install job initializes:

* The admin account.
* The permissions of the admin account.
* The permissions of the backend.

Therefore, the issues could be linked to:

* The reachability of the authentication server Keycloak.
* The reachability of the authorization server SpiceDB.
* A programming error.

The first issue is very likely caused by configuration or network issue.

The second issue is very unlikely because the authorization server can only be accessible internally. Meaning, the Helm Chart should have already been configured for the authorization server to be reachable.

### Investigation

{% code title="bash" overflow="wrap" %}

```bash
kubectl logs -n demo 'toucan-stack-postinstall-...' -c <create-relationship/init-workspace>
```

{% endcode %}

Logs should indicates the errors. Search the errors on Google.

Issues could be linked to (but not limited to):

* A programming error.

### Mitigation

Contact the support for help.

## Vault is in `CrashLoopBackOff` state

The vault container is crashing repeatedly, stuck in crash loop.

The issue is a **configuration** issue, or a **network** issue.

### Detection

{% code title="bash" overflow="wrap" %}

```bash
kubectl get pods --all-namespaces
kubectl get events --all-namespaces
```

{% endcode %}

With events looking like:

{% code title="Example" overflow="wrap" %}

```bash
Events:
  Type     Reason               Age                 From               Message
  ----     ------               ----                ----               -------
  Warning  FailedPostStartHook  35s (x3 over 117s)  kubelet            PostStartHook failed
  Normal   Killing              35s (x3 over 117s)  kubelet            FailedPostStartHook
  Warning  BackOff              16s (x7 over 86s)   kubelet            Back-off restarting failed container server in pod toucan-stack-vault-server-0_demo(7b241ae3-4338-4dbb-9017-a74b22d6bfb4)
```

{% endcode %}

### Possible causes

On bootstrap, if the `vault` container is crashing, it's very likely linked to the `PostStart` lifecycle Hook.

The lifecycle Hook is responsible for:

1. Fetching or inserting the vault bootstraping secret.
2. Setup the KV2 secrets engine.

Step 1 can fail if **RBAC has been disabled**: configuration issue.

Lastly, it can also fail due to implementation errors.

### Investigation

{% code title="bash" overflow="wrap" %}

```bash
# Check the log of the lifecycle hook.
# NOTE: It might not show anything.
kubectl logs toucan-stack-vault-server-0 -c tail-vault-init -n <namespace>
kubectl describe pod toucan-stack-vault-server-0 -n <namespace>
```

{% endcode %}

### Mitigation

#### Failed at step 1

Check if the RBAC is properly configured:

* A `Role` and `RoleBinding` both named `toucan-stack-vault-server-secret-manager` (or similar) must be present.
* A `ServiceAccount` named `toucan-stack-vault-server` (or similar) must be present.

#### Unknown failures

Contact the support.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs-v3.toucantoco.com/self-hosted-toucan/troubleshooting/bootstraping.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.