Skip to main content

Trouble Shooting

Use the latest aqua and aqua-registry

If aqua and aqua-registry are old, please update them.

Set AQUA_LOG_LEVEL=debug

When aqua doesn't work, the environment variable AQUA_LOG_LEVEL is helpful for the debug.

For example,

$ AQUA_LOG_LEVEL=debug kind --help
DEBU[0000] CLI args config= log_level=debug program=aqua
DEBU[0000] install the package package_name=kubernetes-sigs/kind package_version=v0.11.1 program=aqua registry=standard
DEBU[0000] check if the package is already installed package_name=kubernetes-sigs/kind package_version=v0.11.1 program=aqua registry=standard
DEBU[0000] check the permission file_name=kind
DEBU[0000] execute the command exe_path=/Users/shunsuke-suzuki/.aqua/pkgs/http/kind.sigs.k8s.io/dl/v0.11.1/kind-darwin-amd64/kind-darwin-amd64 program=aqua
DEBU[0000] command was executed but it failed error="fork/exec /Users/shunsuke-suzuki/.aqua/pkgs/http/kind.sigs.k8s.io/dl/v0.11.1/kind-darwin-amd64/kind-darwin-amd64: exec format error" exe_path=/Users/shunsuke-suzuki/.aqua/pkgs/http/kind.sigs.k8s.io/dl/v0.11.1/kind-darwin-amd64/kind-darwin-amd64 exit_code=-1 program=aqua
DEBU[0000] command failed error="fork/exec /Users/shunsuke-suzuki/.aqua/pkgs/http/kind.sigs.k8s.io/dl/v0.11.1/kind-darwin-amd64/kind-darwin-amd64: exec format error" exit_code=-1 program=aqua

In the above case, kind is already installed but the exec format error occured. I reinstalled kind then the problem has been solved.

# uninstall kind
$ rm -R /Users/shunsuke-suzuki/.aqua/pkgs/http/kind.sigs.k8s.io/dl/v0.11.1/kind-darwin-amd64
# kind is reinstalled by Lazy Install
$ kind --help

Tracing and CPU Profiling

If you encounter any performance issue, please see Tracing and CPU Profiling.

check file_src is correct

If aqua outputs the warning or error check file_src is correct, this means that the asset was downloaded and unarchived but the executable file wasn't found. Probably this is the problem of the Registry, so please update the Registry.

e.g.

$ aqua i
WARN[0000] check file_src is correct aqua_version=1.15.1 env=darwin/arm64 error="exe_path isn't found: stat /Users/shunsukesuzuki/.local/share/aquaproj-aqua/pkgs/github_release/github.com/neovim/neovim/v0.7.2/nvim-macos.tar.gz/nvim-osx64/bin/nvim: no such file or directory" exe_path=/Users/shunsukesuzuki/.local/share/aquaproj-aqua/pkgs/github_release/github.com/neovim/neovim/v0.7.2/nvim-macos.tar.gz/nvim-osx64/bin/nvim file_name=nvim package=neovim/neovim package_name=neovim/neovim package_version=v0.7.2 program=aqua registry=standard

In this case, the file /Users/shunsukesuzuki/.local/share/aquaproj-aqua/pkgs/github_release/github.com/neovim/neovim/v0.7.2/nvim-macos.tar.gz/nvim-osx64/bin/nvim wasn't found.

Please check the correct path.

$ ls /Users/shunsukesuzuki/.local/share/aquaproj-aqua/pkgs/github_release/github.com/neovim/neovim/v0.7.2/nvim-macos.tar.gz
nvim-macos

The directory name was not nvim-osx but nvim-macos.

$ ls /Users/shunsukesuzuki/.local/share/aquaproj-aqua/pkgs/github_release/github.com/neovim/neovim/v0.7.2/nvim-macos.tar.gz/nvim-macos/bin 
nvim

So we fixed the Standard Registry.

the asset isn't found

If aqua outputs the error the asset isn't found, the following are possible causes.

  • The release doesn't exist
    • Please fix the version
  • GitHub Releases has no assets yet
    • Please wait for uploading them. This isn't a problem of aqua
  • Assets for only specific pair of OS and Arch aren't uploaded
  • Asset name format was changed from the specific version
    • You have to fix the Registry

GitHub API Rate Limit, 403 error

Please set GitHub Access Token to the environment variable GITHUB_TOKEN or AQUA_GITHUB_TOKEN.

Packages aren't installed

Maybe your OS and Arch isn't supported by the package's supported_envs. Please check the Registry Configuration.

Command is not found

If command -v <command> exits with non zero, the following are possible causes.

  • AQUA_ROOT_DIR/bin (AQUA_ROOT_DIR/bat in case of PowerShell) isn't added to the environment variable PATH
    • e.g. $ export PATH=$HOME/.local/share/aquaproj-aqua/bin:$PATH
  • the symbolic link isn't created in AQUA_ROOT_DIR/bin
    • Please run aqua i -l
  • the command name is wrong

You can check the package's command names by aqua g command. For example, the command name of the package cli/cli is gh.

$ aqua g
  docker-slim/docker-slim [docker-slim, docker-slim-sensor]
corneliusweig/rakkess/access-matrix [kubectl-access_matrix]
CircleCI-Public/circleci-cli [circleci]
> cli/cli [gh]: github
4/660
> cli/cli

If the symbolic link isn't created by aqua i -l, the following are possible causes.

  • Your OS and Arch isn't supported by the package's supported_envs
  • the package isn't added in configuration files

aqua finds the configuration files and packages according to the rule.

Please check configuration files and your current directory.

If command -v <command> exits with zero but command can't executed by the error error="command is not found", the following are possible causes.

e.g.

$ gh version
FATA[0000] aqua failed aqua_version=1.19.2 error="command is not found" exe_name=gh program=aqua

aqua finds the configuration files and packages according to the rule.

Please check configuration files and your current directory.