agentleFS
acquiaacquia/acquia-skills-private/skills/acli/troubleshooting/SKILL.md

troubleshooting

Skill1 starsChanged 7 months agoMITView on GitHub

Use when acli commands fail, return unexpected errors, authentication breaks, or the CLI behaves unexpectedly.

  • Reads credentials
  • Deletes or force-pushes

29 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use task-breakdown and architecture.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ttmouseSkill

    task-breakdown

    专业的任务拆解器,将复杂需求拆分成"独立可运行与可演示"的最小闭环任务卡。严格按照纵向切片、单一数据变化、单一入口原则,确保每张任务卡都能在单回合实现并验证。当用户说"帮我拆解一下任务"、"用任务拆解器分析"、"按规范拆分"或需要将一个大的开发需求拆分成可执行的小任务时使用。输出格式严格按照[src/renderer/TODO.md]标准存储。

    Also in 3 projects that use this

  • AnthropicSkill

    architecture

    Create or evaluate an architecture decision record (ADR). Use when choosing between technologies (e.g., Kafka vs SQS), documenting a design decision with trade-offs and consequences, reviewing a system design proposal, or designing a new component from requirements and constraints.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 26 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Cause: Update didn't complete or PATH changed.

    line 59
  2. Distinctive:

    Check if you can see the application or resource

    line 103

“Common” is measured: kept by at least 6 in 10 of the 26 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Troubleshooting Acquia CLI

Use when:

  • Diagnosing acli authentication failures
  • Resolving command errors or unexpected output
  • Collecting information before contacting support

General Issues

"Command not found: acli"

Cause: The binary isn't in your system PATH.

Solutions:

# Check if it's installed
which acli

# If nothing, add to PATH
export PATH="/usr/local/bin:$PATH"

# Test
acli --version

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

"Permission denied" when running acli

Cause: The binary isn't executable.

Solution:

chmod +x /usr/local/bin/acli
acli --version

"acli: command not found" after updating

Cause: Update didn't complete or PATH changed.

Solution:

# Reinstall
curl -fsSL https://github.com/acquia/cli/releases/latest/download/acli \
  -o /usr/local/bin/acli
chmod +x /usr/local/bin/acli

# Verify
acli --version

Authentication Issues

"Error: Failed to authenticate"

Cause: Your authentication token expired or isn't valid.

Solution:

# Re-authenticate
acli auth:login

# This opens your browser to authorize again

"Error: Access Denied"

Cause: Your account doesn't have permission to access the resource.

Solutions:

  1. Check you're logged in with the right account:
    acli auth:me
  2. Verify you have access in Acquia Cloud UI:
  3. Log out and back in:
    acli auth:logout
    acli auth:login

"Invalid JSON in credentials.json"

Cause: Credentials file is corrupted.

Solution:

# Remove the corrupted file
rm -rf ~/.acquia/cloud_api/

# Re-authenticate
acli auth:login

IDE Issues

IDE won't start

Symptoms: IDE shows "Starting..." indefinitely or won't load.

Solutions:

  1. Try restarting IDE services:
    acli ide:service-stop
    acli ide:service-start
  2. Check IDE status:
    acli ide:info
  3. Wait if newly created: New IDEs take 2-3 minutes to start. Check again in a minute.
  4. Try creating a new IDE:
    acli ide:create

IDE is very slow

Causes: Hibernation waking, stuck processes, or resource limits

Solutions:

  1. Wait if waking from hibernation: IDEs waking take 30-60 seconds. Be patient.
  2. Clear Drupal caches:
    acli remote:drush cr
  3. Restart IDE:
    acli ide:service-restart
  4. Create a fresh IDE:
    acli ide:create --label "Fresh IDE"

"Access Denied" when opening IDE

Cause: Your SSH key isn't set up.

Solution:

# Create an SSH key
acli ssh-key:create

# Try accessing IDE again
acli ide:open

IDE appears deleted but still exists

Cause: The IDE is hibernated or the listing is cached.

Solution:

# Clear cache and list again
acli self:clear-caches
acli ide:list

SSH Key Issues

"Permission denied (publickey)"

Cause: SSH key isn't set up or not used correctly.

Solutions:

  1. Verify SSH key exists:
    ls -la ~/.ssh/id_rsa
  2. If not, create one:
    acli ssh-key:create
  3. Check permissions (must be 600):
    chmod 600 ~/.ssh/id_rsa
  4. Verify key is added to Acquia account:
    acli ssh-key:list

"SSH key not found when creating IDE"

Cause: IDE creation requires an SSH key for secure access.

Solution:

# Create SSH key first
acli ssh-key:create

# Then create IDE
acli ide:create

"Multiple SSH keys - which one to use?"

Solution:

Add to ~/.ssh/config:

Host ide-*.ides.acquia.com
  IdentityFile ~/.ssh/my_custom_key

Application & Environment Issues

"No applications found"

Cause: You don't have access to any applications yet.

Solutions:

  1. Check if you're in a team:
    acli auth:me
  2. Ask your team admin to add you to an application

"Error: Application not found"

Cause: Wrong application UUID or no access.

Solutions:

  1. List applications to find the right one:
    acli api:applications:list
  2. Use the correct application:
    acli ide:create --application=<correct-uuid>

Command Execution Issues

"Error: Drush command failed"

Cause: Drush error in your Drupal site.

Solutions:

  1. Check Drush output for details:
    acli remote:drush status
  2. Clear caches:
    acli remote:drush cr

"Error: Could not connect to remote server"

Cause: Network connectivity or SSH key issue.

Solutions:

  1. Check SSH key setup:
    acli ssh-key:list
  2. Try verbose output for details:
    acli -vvv <command>

Performance Issues

Commands taking too long

Solutions:

  1. Try again (might be temporary)
  2. Check internet connection:
    ping acquia.com
  3. Try with shorter timeout:
    acli <command> --no-wait

Cache causing stale data

Cause: CLI caches API responses.

Solutions:

# Clear cache
acli self:clear-caches   # aliases: acli cc, acli cr

# Try the command again
acli <command>

# Or run with --no-cache if supported
acli <command> --no-cache

Getting Help

Check your acli version

acli --version

Enable debug output

# Run any command with verbose output
acli -vvv <command>

# Save to a log file
acli -vvv <command> > debug.log 2>&1

View all help

# General help
acli --help

# List all commands
acli list

# Help for a specific command
acli <command> --help

Getting Help from Support

Before contacting support, gather info

# Your version
acli --version

# Your account info
acli auth:me

# Your applications
acli api:applications:list

# Your IDEs
acli ide:list

# Your SSH keys
acli ssh-key:list

# Debug output of the problem command
acli -vvv <command> 2>&1 | tee debug.log

Contact Acquia Support


Common Error Messages

ErrorMeaningSolution
"Error: Access Denied"You don't have permissionCheck account access, team membership
"Command not found"Binary not in PATHCheck installation, verify PATH
"Failed to authenticate"Token expired or invalidRe-run acli auth:login
"SSH Key not found"IDE needs SSH keyCreate key with acli ssh-key:create
"IDE not starting"IDE provisioning slow or failedWait 2-3 min, restart, or create new
"Permission denied (publickey)"SSH key issueVerify key setup: acli ssh-key:list
"No applications found"No team accessAsk admin to add you to team

Advanced Troubleshooting

Check API responses

# See what the API is returning
acli -vvv <command> 2>&1 | grep -A 5 "Response:"

Reset all configuration

# CAUTION: This clears everything
rm -rf ~/.acquia

# Re-authenticate
acli auth:login

Best Practices

  1. Stay updated — Run acli self:update regularly; many errors are fixed in newer versions.
  2. Check authentication first — Run acli auth:me before blaming other commands.
  3. Use verbose mode — Add -vvv to any failing command to see detailed error output.

Still stuck? Contact Acquia Support

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.