Docs › Troubleshooting › Install and update problems

Install and update problems

Fix installer warnings, the astra command, Linux packages, and updates that do not download or install.

On this page

How to install is on Install AstraCode, and how updates work is on Updates. Update problems are logged in the AstraCode MCP output channel: run AstraCode: MCP: Show Connection Log to read the reason in full.

Updating

The editor downloads updates on its own where it can, and never restarts without your click. When the editor will not start, or you prefer a terminal, each platform has one command, and each accepts --check to say what is available without changing anything:

InstallCommand
macOSastra -update
Windowsastracode -update
Linux .deb or .rpmastracode-update, or astracode -update
Linux .tar.gz./bin/astracode -update, from the folder you extracted

Details are in Install AstraCode, under Update AstraCode, and in Updates.

macOS warns that the app cannot be opened

Cause: AstraCode is signed and notarised, so Gatekeeper opens it without a warning. A warning means the download did not finish.

  1. Delete the .dmg.
  2. Download it again from the download page.
  3. Drag AstraCode into Applications and open it from there.

Windows protected your PC

Cause: SmartScreen shows this for a signature it has not seen often yet. It does not mean anything is wrong with the file.

  1. Choose More info.
  2. Choose Run anyway.

Ubuntu says Potentially unsafe

Cause: Ubuntu's App Center labels every downloaded package this way, whoever made it.

  1. Install from the AstraCode apt repository instead, as shown on Install AstraCode. Your package manager then checks every download against our key.
  2. Or install the file from a terminal: sudo apt install ./AstraCode-linux-x64.deb.

astra: command not found

Cause: the astra command was not linked onto your PATH, or the terminal was open before it was.

  1. On macOS, run AstraCode: Install 'astra' Command in PATH, or choose Install under Command line in AstraCode Settings > General.
  2. If the editor asks for your administrator password, enter it in the system's own prompt. That links the command into /usr/local/bin.
  3. Open a new terminal and run astra .

On Linux, the .deb and .rpm packages put astracode on your PATH already. A .tar.gz install runs as ~/astracode/bin/astracode, or wherever you extracted it.

Could not install the "astra" command: followed by a reason, often after the password prompt was cancelled. Run the install command again and complete the prompt. This build has no command-line launcher in its bundle. means this install has no astra to link; use the command for your platform in the Updating table above.

astracode-update: command not found

  1. On macOS, run AstraCode: Install 'astra' Command in PATH. It links astracode-update beside astra. Or use astra -update.
  2. On Linux with a .deb or .rpm, it is at /usr/bin/astracode-update. astracode -update does the same.

Could not reach the update feed

The editor shows Could not reach the update feed. Try again in a moment. or AstraCode could not check for updates: followed by a reason.

Cause: the editor could not reach astracode.io. The reason names what failed, for example the server could not be found (check your connection or DNS).

  1. Check your connection, and that a VPN or proxy allows astracode.io.
  2. Run AstraCode: Check for Updates again.

This is a development build; there is nothing to update. means this copy was not installed from a release. Install it from the download page.

Update needs you

The status bar shows Update needs you, and a notification says the new version could not be installed automatically: followed by a reason, with Try again and Download manually.

  1. Read the reason; the sections below cover each one.
  2. Choose Try again when it is offered. It is offered only when retrying can help, such as after a dropped connection.
  3. Otherwise choose Download manually, or use the terminal command for your platform.

macOS: no permission to replace the application

The editor shows Could not install automatically: followed by no permission to replace the application, and advice to grant App Management.

Cause: on macOS 14 and later, an app needs the App Management permission to replace another app.

  1. Open System Settings > Privacy & Security > App Management.
  2. Switch AstraCode on.
  3. Run AstraCode: Check for Updates, or choose Open Download Page and install the new version by hand. astra -update in Terminal also works.

macOS: the download is not correctly signed

The reason is the downloaded application is not correctly signed, was not notarised by Apple, was signed by a different developer, or this build is not signed, so an update cannot be verified.

Cause: the editor installs an update only when it is signed by the same developer as the copy you run. No retry is offered, on purpose.

  1. Download AstraCode from the download page.
  2. Install it over the current copy. A copy you re-signed yourself cannot update itself until it is replaced from the download.

the download did not arrive intact or the download did not contain an application: choose Try again, or download it by hand.

Linux packages: updates are not installed for you

Cause: a .deb or .rpm belongs to apt or dnf, so the editor does not replace its files. The notice AstraCode with the new version is available offers Update now, Copy the command and Ignore this version.

  1. Choose Update now. A terminal named AstraCode update opens in the editor and upgrades through apt or dnf; enter your password when it asks.
  2. Or choose Copy the command and run it yourself: sudo apt update && sudo apt install --only-upgrade astracode, or sudo dnf upgrade astracode.
  3. Restart AstraCode when it finishes.

If apt says AstraCode is already the newest version, the AstraCode repository is not registered on this machine. Add it as shown on Install AstraCode, then upgrade again.

Linux tarball: the folder is not writable by this user

The reason is the install folder is not writable by this user, so it cannot update itself.

Cause: the tarball was extracted with sudo, so root owns it.

  1. Download the current .tar.gz from the download page.
  2. Extract it as yourself, into your home folder: mkdir -p ~/astracode && tar -xzf AstraCode-linux-x64.tar.gz -C ~/astracode
  3. Run ~/astracode/install-desktop.sh to update the menu entry.
  4. Delete the old root-owned copy.

the download did not match its checksum or the download does not look like an AstraCode build: choose Try again, or download it by hand.

Windows: the installer was cancelled or stopped

The reason is the installer was cancelled, the installer could not be started or the installer stopped with code followed by a number.

Cause: the Windows permission prompt was declined, or the installer failed.

  1. Choose Try again, and accept the permission prompt.
  2. If it fails again, close AstraCode and run the installer from the download page.

A copy unpacked from a zip, or copied from another machine, cannot update itself. Install with the user or system installer instead. The signature reasons (the download is not validly signed, the download is signed by somebody else) mean the same as on macOS: download it again from the site.

Network and disk reasons

ReasonWhat to do
the download did not finish because a connection reasonCheck the connection, then Try again.
a proxy refused the downloadAllow astracode.io through the proxy, or download by hand.
the disk is fullFree some space, then Try again.
it could not write to its folder (permission denied)The staging folder is not writable. On macOS and Linux it is ~/Library/Caches/AstraCode/updates; on Windows %LOCALAPPDATA%\AstraCode\updates. Fix its permissions.
the download arrived incomplete, or the server answered with an errorTry again in a few minutes.

The terminal updater refuses

MessageWhat to do
AstraCode is still open (it may be asking about unsaved files). Close it, then run astracode-update again. Nothing was changed.Quit AstraCode, saving or discarding open files, and run it again.
/Applications is not writable by you. Re-run with sudo, or update from inside the editor.Run it again with sudo, or use AstraCode: Check for Updates.
Checksum mismatch. Nothing installed.Run it again. If it repeats, download from the site.
The download is not correctly signed. Nothing installed.Download from the site instead.
The new build did not verify in place. The previous version is back.Nothing changed. Download from the site.
astracode-update needs curl.Install curl, then run it again.
This looks like a tarball install.Update from inside the editor, or download the current tarball.

On macOS the terminal updater writes its log to ~/Library/Caches/AstraCode/updates/terminal-update.log.

You ignored a version and want it back

Ignore this version holds until a newer version is published. Run AstraCode: Check for Updates to clear it and be offered the version again.

Your editor's extensions were not brought across

Cause: extensions wait until you are signed in, and the editor then asks Bring your extensions across too? If you chose Not now, it does not ask again. A theme only available from Microsoft's marketplace is skipped.

  1. Open AstraCode Settings > General.
  2. Choose Import beside Import Settings.
  3. Confirm with Import. Nothing you have already chosen in AstraCode is changed.

← Sign-in problems Chat panel problems →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference