> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subtrace.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot: missing SYS_PTRACE capability

Subtrace requires the `SYS_PTRACE` Linux capability in order to work correctly.

Expand the environment you're using to find the exact change to make.

<AccordionGroup>
  <Accordion title="Docker (docker run)">
    If you're using Subtrace in a Docker container via `docker run`, add `--cap-add=SYS_PTRACE` when starting your container. For example:

    ```bash theme={null}
    docker run -it --rm --cap-add=SYS_PTRACE debian:12
    ```
  </Accordion>

  <Accordion title="Docker Compose">
    Add `cap_add: [SYS_PTRACE]` to your service in `compose.yaml`:

    ```yaml {5-6} theme={null}
    services:
      my-app:
        image: ghcr.io/NAMESPACE/IMAGE_NAME:latest
        command: "subtrace run -- ./start.sh"
        cap_add:
          - SYS_PTRACE
    ```
  </Accordion>

  <Accordion title="Kubernetes (Deployments/Pods)">
    Add the capability in the container `securityContext`:

    ```yaml {18-21} theme={null}
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-deployment
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: my-app
      template:
        metadata:
          labels:
            app: my-app
        spec:
          containers:
          - name: my-container
            image: ghcr.io/NAMESPACE/IMAGE_NAME:latest
            securityContext:
              capabilities:
                add:
                  - SYS_PTRACE
    ```
  </Accordion>

  <Accordion title="Amazon ECS (Fargate)">
    The ECS console UI does not expose `linuxParameters.capabilities`. Create a new task definition revision and edit the JSON to include `SYS_PTRACE`:

    ```json theme={null}
    "linuxParameters": {
      "capabilities": {
        "add": ["SYS_PTRACE"]
      }
    },
    ```

    <img src="https://mintcdn.com/subtrace/qpTd5I2XwvFUV3U2/images/ecs/5-task-update-button.png?fit=max&auto=format&n=qpTd5I2XwvFUV3U2&q=85&s=d65c5268a0de9f080207baa521036809" alt="Open JSON editor" width="2438" height="395" data-path="images/ecs/5-task-update-button.png" />

    <img src="https://mintcdn.com/subtrace/qpTd5I2XwvFUV3U2/images/ecs/6-task-json-diff.png?fit=max&auto=format&n=qpTd5I2XwvFUV3U2&q=85&s=1c1b2a9fa0efca439ee87d87addb856f" alt="Highlighted JSON changes" width="2922" height="1479" data-path="images/ecs/6-task-json-diff.png" />
  </Accordion>

  <Accordion title="Flightcontrol">
    Add the `linuxCapabilities` section to your `flightcontrol.json`:

    ```json {3-4} theme={null}
    "target": {
      "type": "fargate",
      "linuxCapabilities": {
        "add": ["SYS_PTRACE"]
      }
    }
    ```
  </Accordion>
</AccordionGroup>