Known Issues

Petal Issues

Petal Name Must Start with petal-*

Symptoms:

  • Petal loads but logging doesn’t work properly

  • Log messages don’t appear in expected log files

  • Petal functionality seems degraded or incomplete

  • Logger instances return incorrect or missing information

Cause:

The Petal App Manager framework expects all petals to follow the petal-* naming convention (kebab-case). Internal systems rely on this naming pattern for proper initialization, logging configuration, and other core functionality.

Solutions:

  1. Rename your petal to follow the convention:

    ❌ Incorrect names:

    • example-petal

    • telemetry

    • my-plugin

    ✅ Correct names:

    • petal-example

    • petal-telemetry

    • petal-my-plugin

  2. Update all references:

    # pyproject.toml
[project]
name = "petal-example"  # Must start with petal-

[project.entry-points."petal.plugins"]
petal_example = "petal_example.plugin:PetalExample"

  3. Reinstall the petal:

    cd ~/petal-app-manager-dev/petal-app-manager
pdm remove old-name
pdm add -e ../petal-example --group dev

Petal Not Getting Loaded

Symptoms:

  • Petal doesn’t appear in /health/detailed endpoint

  • Endpoints defined in your petal return 404

  • No log messages from your petal during startup

  • curl http://localhost:9000/your-petal/health returns 404

Cause:

The most common cause is that the petal is not registered in the proxies.yaml configuration file. Petal App Manager only loads petals that are explicitly enabled in this file.

Solutions:

  1. Check if petal is registered in proxies.yaml:

    cd ~/petal-app-manager-dev/petal-app-manager
# or for production: cd ~/.droneleaf/petal-app-manager
cat proxies.yaml

  2. Add your petal to enabled_petals:

    enabled_petals:
- flight_records
- petal_warehouse
- mission_planner
- petal_user_journey_coordinator
- petal_example  # Add your petal here (use entry point name)

  3. Verify entry point name matches:

    The name in enabled_petals must match the entry point key in your pyproject.toml:

    [project.entry-points."petal.plugins"]
petal_example = "petal_example.plugin:PetalExample"
# ^^^^^^^^^^^^
# This name goes in proxies.yaml

  4. Ensure required proxies are enabled:

    Check that all proxies listed in your petal’s get_required_proxies() are enabled:

    enabled_proxies:
- redis  # If your petal requires redis
- ext_mavlink
- db

petal_dependencies:
petal_example:
- redis  # List the same proxies here

  5. Verify petal is installed:

    pdm list | grep petal-example

  6. Restart Petal App Manager:

    # If running manually
# Stop with Ctrl+C and restart
uvicorn petal_app_manager.main:app --host 0.0.0.0 --port 9000 --log-level info --no-access-log --http h11 --reload

# If running as a service
sudo systemctl restart petal-app-manager

Python 3.11 Issues

Python 3.11 Not Found

Symptoms:

  • python3.11: command not found

  • PDM fails with “No Python interpreter found”

  • Installation scripts fail at Python detection step

Solutions:

  1. Verify Python 3.11 installation:

    which python3.11
python3.11 --version

  2. Check symlinks:

    ls -la /usr/bin/python3.11
ls -la /usr/local/bin/python3.11

  3. Recreate symlinks if missing:

    sudo ln -sf /home/$USER/miniforge3/bin/python3.11 /usr/bin/python3.11
sudo ln -sf /home/$USER/miniforge3/bin/python3.11 /usr/local/bin/python3.11

  4. If any of the above fails, Rerun HEAR_CLI command:

    hear-cli local_machine run_program --p petal_app_manager_prepare_arm

    or for x86_64:

    hear-cli local_machine run_program --p petal_app_manager_prepare_sitl

PDM Issues

PDM Installation Fails

Symptoms:

  • pdm: command not found

  • PDM installation script completes but command not available

  • Permission errors during PDM installation

Solutions:

  1. Verify PDM installation:

    which pdm
pdm --version

  2. Rerun HEAR_CLI command:

    hear-cli local_machine run_program --p petal_app_manager_prepare_arm

    or for x86_64:

    hear-cli local_machine run_program --p petal_app_manager_prepare_sitl

PDM Lock File Issues

Symptoms:

  • pdm install fails with lock file errors

  • Dependency resolution takes very long

  • Version conflicts during installation

Solutions:

  1. Update lock file:

    pdm lock --update-reuse

  2. Clear cache and reinstall:

    pdm cache clear
rm -f pdm.lock
pdm install

Redis Issues

Redis Connection Errors

Symptoms:

  • Connection refused errors

  • redis.exceptions.ConnectionError

  • Petal App Manager health check shows Redis as unhealthy

Solutions:

  1. Check if Redis is running:

    sudo systemctl status redis-server

  2. Start Redis if not running:

    sudo systemctl start redis-server
sudo systemctl enable redis-server

  3. Verify socket permissions:

    ls -la /var/run/redis/redis-server.sock

  4. Fix socket permissions if needed:

    sudo chmod 777 /var/run/redis/redis-server.sock

Redis Configuration Issues

Symptoms:

  • Redis starts but Petal App Manager can’t connect via UNIX socket

  • No such file or directory for socket path

  • Permission denied on socket

Solutions:

  1. Verify UNIX socket is enabled in Redis config:

    grep unixsocket /etc/redis/redis.conf

  2. Expected configuration:

    unixsocket /var/run/redis/redis-server.sock
unixsocketperm 777

  3. Update configuration and restart:

    sudo nano /etc/redis/redis.conf
sudo systemctl restart redis-server

  4. Test socket connection:

    redis-cli -s /var/run/redis/redis-server.sock ping
# Should return: PONG

  5. If any of the above fails, Rerun HEAR_CLI command:

    hear-cli local_machine run_program --p petal_app_manager_prepare_arm

    or for x86_64:

    hear-cli local_machine run_program --p petal_app_manager_prepare_sitl

MQTT Issues

MQTT Proxy Fails on Fresh Installation

Symptoms:

  • Petal App Manager fails to start in development environment

  • MQTT proxy shows errors or remains unhealthy

  • Application logs show MQTT connection failures

  • Service fails to start after fresh installation

Cause:

On a fresh installation, the MQTT proxy requires organization provisioning to be completed before it can connect properly. Without provisioning, the MQTT proxy lacks necessary organization and device identifiers.

Solutions:

Development Environment:

  1. Start Petal App Manager manually (ignore MQTT errors initially):

    cd ~/petal-app-manager-dev/petal-app-manager
uvicorn petal_app_manager.main:app --host 0.0.0.0 --port 9000 --log-level info --no-access-log --http h11

  2. Complete local provisioning steps:

    • Open http://localhost:80 in your browser

    • Follow the provisioning wizard

    • Use fly.droneleaf.io to generate the API key when prompted

    • Complete the additional provisioning steps shown in the localhost interface

  3. Restart Petal App Manager:

    # Stop with Ctrl+C and restart
uvicorn petal_app_manager.main:app --reload --host 0.0.0.0 --port 9000 --log-level info --no-access-log --http h11

  4. Complete cloud provisioning:

    • Finish any remaining provisioning steps on fly.droneleaf.io

    • Verify the device appears in the cloud dashboard

Production/Service Environment:

Warning

Known Concern: When running as a systemd service on a fresh installation, the service may fail to start or repeatedly restart due to MQTT provisioning requirements. This behavior needs further investigation.

Workaround for Service Deployment:

  1. Temporarily disable MQTT proxy during initial setup:

    cd ~/.droneleaf/petal-app-manager
nano proxies.yaml

    Comment out or remove mqtt from enabled_proxies:

    enabled_proxies:
# - mqtt  # Temporarily disabled for provisioning
- redis
- ext_mavlink
- db

  2. Start the service:

    sudo systemctl start petal-app-manager
sudo systemctl status petal-app-manager

  3. Complete provisioning via web interface

  4. Re-enable MQTT proxy:

    nano ~/.droneleaf/petal-app-manager/proxies.yaml

    Uncomment mqtt in enabled_proxies:

    enabled_proxies:
- mqtt  # Re-enabled after provisioning
- redis
- ext_mavlink
- db

  5. Restart the service:

    sudo systemctl restart petal-app-manager

Alternative: Pre-provision Before Service Installation

  1. Run Petal App Manager manually first

  2. Complete all provisioning steps

  3. Stop manual instance

  4. Install and start as service

Verification:

Check MQTT proxy health after provisioning:

curl http://localhost:9000/health/detailed | jq '.proxies.mqtt'

Expected healthy output:

{
  "status": "healthy",
  "is_connected": true,
  "organization_id": "your-org-id",
  "device_id": "Instance-your-machine-id"
}

Port Conflicts

Port 9000 Already in Use

Symptoms:

  • Address already in use error when starting Petal App Manager

  • Cannot start uvicorn server

  • Application fails to bind to port

Cause:

This typically occurs when trying to run Petal App Manager using uvicorn while the systemd service is already running, or when another process is using port 9000.

Solutions:

  1. Check what’s using port 9000:

    sudo lsof -i :9000

  2. Stop the systemd service (if running):

    sudo systemctl stop petal-app-manager
sudo systemctl status petal-app-manager

  3. Kill the conflicting process:

    # Find the process ID (PID) from lsof output
sudo kill <PID>

Reporting Issues

If you encounter issues not covered here:

GitHub Issues

Report bugs and request features at:

Include in Your Report

  1. Environment information:

    python3.11 --version
pdm --version
redis-server --version

  2. Log files:

    # Application logs
tail -100 app.log

# System logs
sudo journalctl -u petal-app-manager -n 100

  3. Configuration:

    # Sanitize sensitive data before sharing
cat proxies.yaml
cat .env | grep -v TOKEN | grep -v PASSWORD

  4. Steps to reproduce the issue

  5. Expected vs actual behavior

Getting Help