agentsclimarketplace

Troubleshooting

Skill acquia/acquia-skills-private/skills/acli/troubleshooting

Install
npx -y skills add acquia/acquia-skills-private --skill troubleshooting

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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

The file declares its own license as Proprietary. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

8.1 KB, as published. Nobody here has run it

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

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.