Skip to main content

Troubleshooting

Common issues and solutions when using asc-cli.

Installation Issues​

Command Not Found​

Symptom:

zsh: command not found: asc

Solutions:

  1. Check PATH includes install location:
# For pip user install
export PATH="$HOME/.local/bin:$PATH"

# For uv
export PATH="$HOME/.local/bin:$PATH"

# Add to ~/.zshrc or ~/.bashrc for persistence
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
  1. Verify installation:
pip show asc-cli
# or
uv tool list | grep asc
  1. Reinstall:
pip uninstall asc-cli
pip install asc-cli

Python Version Error​

Symptom:

ERROR: asc-cli requires Python 3.9+

Solution:

# Check Python version
python3 --version

# Install with specific Python
python3.11 -m pip install asc-cli

# Or use uv (handles Python automatically)
uv tool install asc-cli

Authentication Issues​

Not Authenticated​

Symptom:

Error: Not authenticated. Run 'asc auth login' first.

Solutions:

  1. Run login:
asc auth login
  1. Check credentials file exists:
ls ~/.config/asc-cli/credentials
  1. Verify environment variables (if using):
echo $ASC_ISSUER_ID
echo $ASC_KEY_ID
echo $ASC_PRIVATE_KEY_PATH

Invalid Token​

Symptom:

Error: Invalid API credentials. JWT token rejected by App Store Connect.

Solutions:

  1. Verify credentials match App Store Connect:

    • Log into App Store Connect
    • Go to Users and Access → Integrations → App Store Connect API
    • Compare Issuer ID and Key ID

  2. Check .p8 file:

# Verify file exists and is readable
cat ~/.config/asc-cli/AuthKey_*.p8

# Should show:
# -----BEGIN PRIVATE KEY-----
# (base64 content)
# -----END PRIVATE KEY-----

  1. Re-download key if corrupted:

    • Keys can only be downloaded once
    • If corrupted, generate a new key in App Store Connect

  2. Check key hasn't been revoked:

    • In App Store Connect, verify key is still active

Permission Denied​

Symptom:

Error: Insufficient permissions for this operation.
Required: Admin or App Manager
Your role: Developer

Solution:

  1. Check your API key role in App Store Connect
  2. Request Admin or App Manager role from team admin
  3. Or generate new key with appropriate role

Token Expired​

Symptom:

Error: Token expired. Re-authenticating...
Error: Failed to refresh token.

Solutions:

  1. Re-run login:
asc auth login
  1. Check system clock is accurate:
date

API Errors​

Rate Limited​

Symptom:

Error: Rate limited by App Store Connect. Retry after 60 seconds.

Solutions:

  1. Wait and retry:
sleep 60 && asc apps list
  1. For bulk operations, use smaller batches:
# Instead of all at once
asc subscriptions pricing set SUB_ID --price 2.99 --all

# Do in batches
asc subscriptions pricing set SUB_ID --price 2.99 -t USA -t CAN -t GBR
# Wait
asc subscriptions pricing set SUB_ID --price 2.99 -t DEU -t FRA -t ITA
  1. Enable rate limit handling:
asc --rate-limit-retry apps list

Server Error (500)​

Symptom:

Error: App Store Connect server error. Status: 500

Solutions:

  1. Check Apple System Status
  2. Wait and retry later
  3. If persistent, contact Apple Developer Support

Resource Not Found​

Symptom:

Error: App not found: com.example.app

Solutions:

  1. Verify bundle ID:
asc apps list

  1. Check for typos in bundle ID

  2. Ensure app exists in your App Store Connect account

Subscription Issues​

Subscription Not Found​

Symptom:

Error: Subscription not found: com.example.pro.monthly

Solutions:

  1. List available subscriptions:
asc subscriptions list BUNDLE_ID

  1. Use correct product ID (not display name)

  2. Subscription may need to be created in App Store Connect web UI first

Invalid Subscription State​

Symptom:

Error: Cannot modify subscription - invalid state: MISSING_METADATA

Solutions:

  1. Complete subscription setup in App Store Connect:

    • Add description
    • Add pricing (at least one territory)
    • Review status indicators

  2. Subscription must be in READY_TO_SUBMIT or higher

Price Point Not Found​

Symptom:

Error: Price $2.50 does not match any Apple price point.

Solutions:

  1. Use valid Apple price point:
# List available price points
asc subscriptions pricing points

# Use exact price
asc subscriptions pricing set SUB_ID --price 2.49
# or
asc subscriptions pricing set SUB_ID --price 2.99
  1. See Apple's price points

YAML/Bulk Issues​

Invalid YAML Syntax​

Symptom:

Error: Invalid YAML at line 15: expected indentation

Solutions:

  1. Validate YAML syntax:
asc bulk validate subscriptions.yaml

  1. Use consistent indentation (2 spaces recommended)

  2. Check for tabs vs spaces mixing

  3. Online YAML validators can help identify issues

Schema Validation Error​

Symptom:

Error: Validation failed: 'price_usd' is required for subscription

Solutions:

  1. Check against schema:
asc bulk schema --output schema.json
  1. Ensure all required fields present:
subscriptions:
  - product_id: app.pro.monthly    # Required
    price_usd: 2.99                # Required
    territories: all               # Required

Partial Apply Failure​

Symptom:

Error: Apply failed at subscription 3 of 5.
Successfully applied: 2
Failed: 1
Remaining: 2

Solutions:

  1. Check error message for specific issue

  2. Fix the failing subscription

  3. Resume with remaining:

asc bulk apply subscriptions.yaml --skip 2

Mock Server Issues​

Mock Server Won't Start​

Symptom:

Error: Cannot start mock server on port 8080

Solutions:

  1. Check if port is in use:
lsof -i :8080
  1. Use different port:
asc mock start --port 8081
export ASC_MOCK_URL=http://localhost:8081
  1. Stop existing instance:
asc mock stop
asc mock start

Mock Not Working​

Symptom: Commands still hitting production API

Solutions:

  1. Verify mock is enabled:
export ASC_MOCK=true
asc apps list
  1. Check mock server running:
asc mock status
  1. Verify correct URL:
echo $ASC_MOCK_URL

Debugging​

Enable Verbose Output​

asc -v subscriptions list BUNDLE_ID

Enable Debug Mode​

asc --debug apps list

Shows API requests, responses, and timing.

Check Configuration​

asc config show

Displays all active configuration values.

Validate Setup​

asc auth test

Tests complete authentication flow.

Getting Help​

Check Version​

asc --version

View Help​

asc --help
asc subscriptions --help
asc subscriptions pricing --help

Report Issues​

If you encounter a bug:

  1. Gather information:
asc --version
python --version
uname -a
  1. Reproduce with debug:
asc --debug <failing-command> 2>&1 | tee debug.log
  1. Report at GitHub Issues

Learn More​