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

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

```
docker run -it --rm --cap-add=SYS_PTRACE debian:12
```

## Docker Compose
Add `cap_add: [SYS_PTRACE]` to your service in `compose.yaml`:

```
services:
  my-app:
    image: ghcr.io/NAMESPACE/IMAGE_NAME:latest
    command: "subtrace run -- ./start.sh"
    cap_add:
      - SYS_PTRACE
```

## Kubernetes (Deployments/Pods)
Add the capability in the container `securityContext`:

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

## 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`:

```
"linuxParameters": {
  "capabilities": {
    "add": ["SYS_PTRACE"]
  }
},
```

## Flightcontrol
Add the `linuxCapabilities` section to your `flightcontrol.json`:

```
"target": {
  "type": "fargate",
  "linuxCapabilities": {
    "add": ["SYS_PTRACE"]
  }
}
```