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
- Updating
- macOS warns that the app cannot be opened
- Windows protected your PC
- Ubuntu says Potentially unsafe
- astra: command not found
- astracode-update: command not found
- Could not reach the update feed
- Update needs you
- macOS: no permission to replace the application
- macOS: the download is not correctly signed
- Linux packages: updates are not installed for you
- Linux tarball: the folder is not writable by this user
- Windows: the installer was cancelled or stopped
- Network and disk reasons
- The terminal updater refuses
- You ignored a version and want it back
- Your editor's extensions were not brought across
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:
| Install | Command |
|---|---|
| macOS | astra -update |
| Windows | astracode -update |
Linux .deb or .rpm | astracode-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.
- Delete the
.dmg. - Download it again from the download page.
- 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.
- Choose More info.
- Choose Run anyway.
Ubuntu says Potentially unsafe
Cause: Ubuntu's App Center labels every downloaded package this way, whoever made it.
- Install from the AstraCode apt repository instead, as shown on Install AstraCode. Your package manager then checks every download against our key.
- 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.
- On macOS, run AstraCode: Install 'astra' Command in PATH, or choose Install under Command line in AstraCode Settings > General.
- If the editor asks for your administrator password, enter it in the system's own prompt. That links the command into
/usr/local/bin. - 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
- On macOS, run AstraCode: Install 'astra' Command in PATH. It links
astracode-updatebesideastra. Or useastra -update. - On Linux with a
.debor.rpm, it is at/usr/bin/astracode-update.astracode -updatedoes 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).
- Check your connection, and that a VPN or proxy allows
astracode.io. - 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.
- Read the reason; the sections below cover each one.
- Choose Try again when it is offered. It is offered only when retrying can help, such as after a dropped connection.
- 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.
- Open System Settings > Privacy & Security > App Management.
- Switch AstraCode on.
- Run AstraCode: Check for Updates, or choose Open Download Page and install the new version by hand.
astra -updatein 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.
- Download AstraCode from the download page.
- 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.
- Choose Update now. A terminal named AstraCode update opens in the editor and upgrades through apt or dnf; enter your password when it asks.
- Or choose Copy the command and run it yourself:
sudo apt update && sudo apt install --only-upgrade astracode, orsudo dnf upgrade astracode. - 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.
- Download the current
.tar.gzfrom the download page. - Extract it as yourself, into your home folder:
mkdir -p ~/astracode && tar -xzf AstraCode-linux-x64.tar.gz -C ~/astracode - Run
~/astracode/install-desktop.shto update the menu entry. - 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.
- Choose Try again, and accept the permission prompt.
- 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
| Reason | What to do |
|---|---|
| the download did not finish because a connection reason | Check the connection, then Try again. |
| a proxy refused the download | Allow astracode.io through the proxy, or download by hand. |
| the disk is full | Free 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 error | Try again in a few minutes. |
The terminal updater refuses
| Message | What 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.
- Open AstraCode Settings > General.
- Choose Import beside Import Settings.
- 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
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems