Troubleshooting

Init Command Issues

”No recipes found”

$ pilum init
No recipes available

Causes:

1. No embedded recipes in the binary
2. Running a development build

Solutions:

Run with recipe path:

pilum init --recipe-path=./recepies

Or rebuild:

make build

---

Service Discovery

”No services found”

$ pilum deploy
No services to deploy

Causes:

1. No pilum.yaml files
2. Wrong directory
3. Files named incorrectly

Solutions:

Check location:

find . -name "pilum.yaml"

Ensure files are named pilum.yaml (not pilum.yml or service.yaml).

---

”No recipe found for provider”

Error: no recipe found for provider 'my-provider'

Causes:

1. Recipe file missing
2. Provider name mismatch
3. Recipe syntax error

Solutions:

Check recipe exists:

ls recepies/

Verify provider matches:

pilum.yaml

provider: gcp

# Recipe file
provider: gcp  # Must match

Validate YAML:

cat recepies/my-provider-recepie.yaml | python3 -c "import yaml,sys; yaml.safe_load(sys.stdin)"

---

Validation Errors

”recipe requires field ‘X’”

$ pilum check
error: recipe 'gcp-cloud-run' requires field 'region'

Solution:

Add the missing field:

name: my-service
provider: gcp
region: us-central1  # Add this

Check requirements:

cat recepies/gcp-cloud-run-recepie.yaml

---

Nested field errors

Error: recipe 'homebrew' requires field 'homebrew.tap_url'

Solution:

Use nested structure:

name: my-tool
provider: homebrew

homebrew:
  tap_url: https://github.com/org/homebrew-tap
  project_url: https://github.com/org/project

---

Build Failures

”command not found”

Step 1: build binary
  my-service  ✗ - exec: "go": executable file not found

Solution:

Install required tools:

which go && go version
which docker && docker --version
which gcloud && gcloud --version

---

Build timeout

my-service  ✗ (300.0s) - context deadline exceeded

Solutions:

1. Increase timeout in recipe:

steps:
  - name: build binary
    timeout: 600

2. Or use CLI flag:

pilum deploy --timeout=600

3. Test build manually:

cd services/my-service
go build -o dist/app .

---

Docker build fails

Step 2: build docker image
  my-service  ✗ - Dockerfile not found

Solution:

Ensure Dockerfile exists:

ls services/my-service/Dockerfile

---

Authentication Errors

GCP

ERROR: (gcloud.run.deploy) PERMISSION_DENIED

Solution:

gcloud auth login
gcloud auth configure-docker
gcloud config set project YOUR_PROJECT_ID

---

AWS

Unable to locate credentials

Solution:

aws configure
# Or
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1

---

Azure

az login required

Solution:

az login
az acr login --name YOUR_ACR_NAME

---

Push Failures

Registry access denied

Step 3: push to registry
  my-service  ✗ - denied: access forbidden

Solutions:

Authenticate:

# GCP
gcloud auth configure-docker us-central1-docker.pkg.dev

# AWS ECR
aws ecr get-login-password | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com

# Docker Hub
docker login

Check registry URL:

registry_name: us-central1-docker.pkg.dev/my-project/my-repo

---

Parallel Execution

Race conditions

Services interfering during parallel execution.

Solution:

pilum deploy --max-workers=1

Or use service_dir execution mode:

steps:
  - name: build
    execution_mode: service_dir

---

Out of memory

System slows with many parallel builds.

Solution:

pilum deploy --max-workers=2

---

Dry Run Issues

Variables not substituted

my-service: deploy
  [aws s3 sync ./dist s3://${project}-bucket]

Solution:

Ensure field exists:

name: my-service
project: my-project  # Enables ${project}

---

Homebrew Issues

Formula push fails

Step 5: push to tap
  my-cli  ✗ - authentication required

Solution:

export GH_TOKEN="ghp_xxxxx"

Token needs repo scope.

---

Checksum errors

If users report checksum mismatch:

1. Verify release assets
2. Re-run deploy to regenerate formula

---

Debug Mode

For verbose output:

pilum deploy --debug --tag=v1.0.0

Shows:

• Command arguments
• Working directories
• Environment variables
• Full error traces

---

Getting Help

If issues persist:

1. Run with --debug
2. Check GitHub Issues
3. Open a new issue with:
   • Pilum version
   • Full error message
   • pilum.yaml (sanitized)
   • Recipe being used
   • Debug output