Troubleshooting

Common issues and their solutions.

Table of Contents

  1. Attachment Issues
    1. Error: Operation not permitted
      1. Solution 1: Use Same User
      2. Solution 2: Use sudo
      3. Solution 3: Adjust ptrace_scope
      4. Solution 4: SELinux Configuration (RHEL/Fedora)
    2. Error: Process not found
    3. Error: Python debugging symbols not found (Linux, Python < 3.14)
    4. Error: GDB not found (Linux, Python < 3.14)
    5. Error: LLDB not found (macOS, Python < 3.14)
    6. Error: Timeout attaching to process
  2. Observation Issues
    1. No Observation Data
      1. Check Function Name
      2. Confirm Function is Called
      3. Simplify Condition Expression
      4. Increase Observation Count
    2. Incomplete Observation Data
    3. Condition Expression Error
      1. Available Variables
      2. Safe Functions
      3. Examples
  3. Performance Issues
    1. Target Process Slows Down
      1. Use Python 3.12+
      2. Limit Observation Frequency
      3. Reduce Output Depth
      4. Stop Unnecessary Observations
    2. Peeka Client Slow Response
  4. Output Issues
    1. JSON Parsing Error
    2. Garbled Output
  5. Docker Issues
    1. Unable to Attach in Docker Container
      1. docker run
      2. docker-compose.yml
      3. Kubernetes
  6. TUI Issues
    1. TUI Display Abnormal
    2. TUI Colors Broken in Docker Container
    3. TUI Freezes
  7. Other Issues
    1. Socket File Conflict
    2. High Memory Usage
    3. Module Not Found
  8. Getting Help
  9. Related Documentation

Attachment Issues

Error: Operation not permitted

Symptom:

Error: Operation not permitted: ptrace access denied

Cause: Insufficient permissions to attach to the target process.

Solutions:

Solution 1: Use Same User 

# Confirm target process owner
ps -o user= -p <pid>

# Run Peeka with the same user
peeka-cli attach <pid>

Solution 2: Use sudo 

sudo peeka-cli attach <pid>

Solution 3: Adjust ptrace_scope 

# Check current setting
cat /proc/sys/kernel/yama/ptrace_scope

# Temporary modification (for testing)
echo 1 | sudo tee /proc/sys/kernel/yama/ptrace_scope

# Permanent modification
echo "kernel.yama.ptrace_scope = 1" | sudo tee /etc/sysctl.d/10-ptrace.conf
sudo sysctl -p /etc/sysctl.d/10-ptrace.conf

Solution 4: SELinux Configuration (RHEL/Fedora) 

# Check SELinux status
getenforce

# Temporarily allow ptrace
sudo setsebool -P deny_ptrace off

# Or create SELinux policy

Error: Process not found

Symptom:

Error: Process 12345 not found

Cause: PID doesn’t exist or process has exited.

Solution:

# Confirm process exists
ps -p 12345

# Re-find PID
ps aux | grep "your_app"
pgrep -f "your_app.py"

Error: Python debugging symbols not found (Linux, Python < 3.14)

Symptom:

Error: Python debugging symbols not found. Install python3-dbg.

Cause: Python debugging symbols not installed (required for the Linux GDB fallback).

Solution:

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install python3-dbg

# RHEL/CentOS/Fedora
sudo yum install python3-debuginfo

# Verify installation
python3 -c "import sys; print(hasattr(sys, 'gettotalrefcount'))"
# Should output True

Error: GDB not found (Linux, Python < 3.14)

Symptom:

Error: GDB not found. Please install GDB.

Cause: GDB is not installed.

Solution:

# Debian/Ubuntu
sudo apt-get install gdb

# RHEL/CentOS
sudo yum install gdb

# Verify version (requires 7.3+)
gdb --version

Error: LLDB not found (macOS, Python < 3.14)

Symptom:

Error: LLDB not found

Cause: Xcode Command Line Tools are not installed.

Solution:

xcode-select --install
lldb --version

Error: Timeout attaching to process

Symptom:

Error: Timeout attaching to process after 30 seconds

Cause:

  1. Target process is hung or unresponsive
  2. Attach timeout too short
  3. High system load

Solution:

# Solution 1: Increase timeout
peeka-cli attach <pid> --timeout 60

# Solution 2: Check process status
ps -p <pid> -o stat=
# D: Uninterruptible sleep (possibly hung)
# R/S: Normal running

# Solution 3: Check system load
top
uptime

Observation Issues

No Observation Data

Symptom: watch command starts but no observation data is output.

Cause:

  1. Function name spelling error
  2. Function not being called
  3. Condition expression too strict
  4. Observation count limit reached

Solutions:

Check Function Name 

# Use sc/sm to search for correct function name
peeka-cli sc "Calculator"
peeka-cli sm "add"

# Use fully qualified name
peeka-cli watch "demo.Calculator.add"  # ✅
peeka-cli watch "Calculator.add"        # ❌

Confirm Function is Called 

# Check if target process is running
ps -p <pid>

# Check process logs
tail -f /var/log/your_app.log

Simplify Condition Expression 

# First observe without conditions
peeka-cli watch "demo.func" --times 5

# After confirming data, add conditions
peeka-cli watch "demo.func" --condition "cost > 100" --times 5

Increase Observation Count 

# Default -1 (infinite)
peeka-cli watch "demo.func"

# Or explicitly specify
peeka-cli watch "demo.func" --times 100

Incomplete Observation Data

Symptom: Observed parameters or return values show as <truncated> or incomplete.

Cause: Output depth limit.

Solution:

# Increase output depth (default 2)
peeka-cli watch "demo.func" --depth 5

# Depth explanation:
# 1: Only show type
# 2: Show one layer of structure
# 5+: Show deep nesting

Condition Expression Error

Symptom:

Error: Invalid condition expression: name 'invalid_var' is not defined

Cause: Condition expression uses non-existent variables or unsafe functions.

Solutions:

Available Variables 

# ✅ Correct variables
params      # Parameter list
kwargs      # Keyword arguments
returnObj   # Return value
throwExp    # Exception object
cost        # Execution time (milliseconds)
target      # Target object (instance method)

Safe Functions 

# ✅ Allowed functions
len(), str(), int(), float(), bool()
type(), isinstance()
min(), max(), sum()

# ❌ Disallowed functions
eval(), exec(), compile()
open(), read(), write()
__import__()

Examples 

# ✅ Correct
--condition "len(params) > 2"
--condition "params[0] > 100 and cost > 50"
--condition "returnObj is not None"

# ❌ Incorrect
--condition "my_var > 100"           # my_var doesn't exist
--condition "eval('1+1')"            # eval not allowed
--condition "open('/etc/passwd')"    # open not allowed

Performance Issues

Target Process Slows Down

Symptom: After attaching Peeka, target process response slows down.

Cause:

  1. trace command overhead too high (Python < 3.12)
  2. Observation frequency too high
  3. Output depth too large

Solutions:

Use Python 3.12+

Python 3.12+ trace command uses sys.monitoring API with overhead < 5%.

Limit Observation Frequency 

# ✅ Limit observation count
peeka-cli watch "func" --times 10

# ✅ Use conditional filtering
peeka-cli watch "func" --condition "cost > 100"

# ❌ Infinite observation of high-frequency function
peeka-cli watch "high_frequency_func"

Reduce Output Depth 

# ✅ Use default depth
peeka-cli watch "func"  # depth=2

# ❌ Excessive depth
peeka-cli watch "func" --depth 10

Stop Unnecessary Observations 

# Stop watch
peeka-cli reset "func"

# Or detach from process
peeka-cli detach <pid>

Peeka Client Slow Response

Symptom: Peeka commands execute slowly, data transmission has high latency.

Cause:

  1. Observation data volume too large
  2. Unix Socket buffer full
  3. High CPU load

Solutions:

# Reduce data volume
peeka-cli watch "func" --times 10 --condition "cost > 100"

# Check system resources
top
df -h

# Clean up old socket files
rm -f /tmp/peeka_*.sock

Output Issues

JSON Parsing Error

Symptom:

Error: Expecting value: line 1 column 1 (char 0)

Cause: Output contains non-JSON content (such as print statements).

Solutions:

# Extract only JSON lines
peeka-cli watch "func" | grep '^{' | jq

# Or use Python filter
peeka-cli watch "func" | python -c '
import sys, json
for line in sys.stdin:
    try:
        msg = json.loads(line)
        print(json.dumps(msg))
    except:
        pass
'

Garbled Output

Symptom: Output contains garbled characters.

Cause: Encoding issue.

Solutions:

# Set correct locale
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# Or use Python processing
peeka-cli watch "func" | python -c '
import sys
for line in sys.stdin:
    print(line, end="")
' 2>&1 | tee output.log

Docker Issues

Unable to Attach in Docker Container

Symptom:

Error: Operation not permitted (Docker)

Cause: Container lacks SYS_PTRACE capability.

Solutions:

docker run 

docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined your-image

docker-compose.yml 

services:
  app:
    image: your-image
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined

Kubernetes 

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: app
    securityContext:
      capabilities:
        add: ["SYS_PTRACE"]

TUI Issues

TUI Display Abnormal

Symptom: TUI interface display garbled or cannot render properly.

Cause: Terminal compatibility issue.

Solutions:

# Check if terminal type supports 256 color
echo $TERM

# Or use CLI mode
peeka-cli watch "func"

TUI Colors Broken in Docker Container

Symptom: After entering a container via docker exec, TUI colors are missing or Header/Footer are indistinguishable from the main body.

Cause: docker exec does not inherit host terminal environment variables (TERM, COLORTERM). The container defaults to TERM=dumb, and Textual cannot detect truecolor support.

Solutions:

Peeka test images have TERM=xterm-256color and COLORTERM=truecolor baked in. TUI works out of the box via docker exec — no manual env setup needed.

TUI Freezes

Symptom: TUI interface unresponsive.

Cause:

  1. Data flow too fast
  2. Background thread blocking

Solutions:

# Use Ctrl+C to exit

# Use CLI instead
peeka-cli watch "func" --times 10

Other Issues

Socket File Conflict

Symptom:

Error: Address already in use: /tmp/peeka_12345.sock

Cause: Previous abnormal exit didn’t clean up socket file.

Solutions:

# Delete old socket file
rm -f /tmp/peeka_12345.sock

# Or use different socket directory
peeka-cli attach 12345 --socket-dir /tmp/my_peeka

High Memory Usage

Symptom: Peeka or target process has high memory usage.

Cause: Observation data buffer too large.

Solutions:

# Limit observation count
peeka-cli watch "func" --times 100

# Periodically reset observations
peeka-cli reset "func"

# Or detach from process
peeka-cli detach <pid>

Module Not Found

Symptom:

Error: No module named 'peeka'

Cause: Installation issue.

Solutions:

# Reinstall
pip uninstall peeka
pip install peeka

# Or use uv
uv pip install peeka

# Verify installation
python -c "import peeka; print(peeka.__version__)"

Getting Help

If none of the above solutions resolve your issue:

  1. View logs: 
    peeka-cli --verbose attach <pid>

  2. GitHub Issues: https://github.com/peeka-project/peeka/issues

  3. Provide information:
    • Operating system and version
    • Python version
    • Peeka version
    • Complete error message
    • Reproduction steps
  4. Community discussion:
    • GitHub Discussions
    • Stack Overflow (tag: peeka)

Back to top

Copyright © 2026 Peeka contributors. Distributed under the Apache License 2.0.

This site uses Just the Docs, a documentation theme for Jekyll.