Frontastic CLI troubleshooting

macOS refuses to start Frontastic CLI

If you get a message saying that the application can't be started because the developer can't be verified, you have to allow the application in the General tab of the Security and Privacy settings in your System Preferences. See here for more info.

Yarn has errors on installation

Make sure you've done a fresh checkout after using a Frontastic sandbox. Or you can remove all node_modules folders (even those in paas/...) and try again. You can clean up your entire code base to the state of a fresh clone using git clean -f -d -x.

Frontastic CLI claims ports are in use

You might have a Frontastic container/VM running in another directory. Make sure this is shut down properly using vagrant halt in the directory in question. Another reason might be that you have a webserver running locally on port 80 please shut this down before starting the Frontastic CLI.

In rare cases, there might also be a dangling process of a utility used by Frontastic CLI. To check this see if there are processes running named mutagen or traefik. If so, terminate those and try again. If that does still not help, restarting your computer to release the ports from zombie processes might help.

SSH key not recognized

If you get the below error:

Already copied the SSH key to the server but SSH still complains with Pseudo-terminal will not be allocated because stdin is not a terminal

You'll need to check which keys are loaded into your ssh-agent by using ssh-add -L.

If your key isn't in that list, then you'll need to follow the instructions in this article.

If you're using macOS and your passphrase isn't caching and you have to keep re-entering it, you can use the below in your /.ssh/config, which is also explained in more detail in the GitHub article link above.

UseKeychain yes

Host key is unknown

If you get the below error:

WARN 2021/02/01 16:56:02 Host key is unknown, have to add it to known_hosts
ERROR 2021/02/01 16:56:02 Already updated known_hosts but SSH still complains with Pseudo-terminal will not be allocated because stdin is not a terminal.

You'll need to remove the key from known_hosts. To do this run the below command:

ssh-keygen -R your-machine-hostname

If this doesn't fix the issue or if you have keys conflicts, you may need to use the command with IP instead:

ssh-keygen -R your-machine-ip

As an alternative solution, open your local known_hosts file, delete the lines related to the sandbox hostname or IP, and save.

Then run frontastic run and it will be added automatically.

SSH-agent not running

If you're on macOS and the CLI shows you the message ssh-agent doesn't seem to be running, you'll need to make sure your ssh-agent is running. To make sure that it's started at system startup, you can use the command:

sudo launchctl enable system/com.openssh.ssh-agent

Error: Project already running

If you see the error Project already running, this means that there's a .frontastic/mutagen.yml.lock file still running from an unclean stopped filesync process or from one currently running.

Check if a Mutagen process is running by using ps ax | grep mutagen and then kill the process. You can then remove the lock file and try the Frontastic CLI again.


If there's a problem with node_modules (error in Frontastic CLI or Yarn containing ENOENT), or if you want to start over, you can first run the below command:

git clean -fdxn -e .idea

This will do a dry run of the command and print all the files that will be removed. Once you've checked you're happy that the files can be removed, then you can run the below:

git clean -fdx -e .idea

This will throw away all files which aren't tracked by Git and will bring you back to a clean state. You'll need to start with frontastic init again.

client/daemon version mismatch

If you get this filesync error, after upgrading to a recent CLI version:

Err! could not connect to daemon: client/daemon version mismatch (daemon restart recommended)

Delete the whole .frontastic folder and run frontastic init to solve it.

Unable to connect to daemon: connection timed out (is the daemon running?)

If you get the below error:

Attempting to start Mutagen daemon...
Error: unable to connect to daemon: connection timed out (is the daemon running?)
Error: project not running
Error: unable to connect to daemon: connection timed out (is the daemon running?)
INFO 2021/05/05 09:54:00 You may need to provide your sudo password.
INFO 2021/05/05 09:54:00 Updating your hostsfile...
INFO 2021/05/05 09:54:00 Updated hostsfile.
could not terminate mutagen daemon: exit status 1

You can run the below to avoid this issue:

frontastic run --defaultMutagenDataDir

This lets Mutagen store its data under the default directory, which is .mutagen in your home directory instead of inside the .frontastic directory.

Only 1 Mutagen instance can run at the same time and the Mutagen cache can cause problems. So, if you're using the --defaultMutagenDataDir flag and run into issues, try to delete the .mutagen directory in your home directory.

SSH connection doesn't close

If you're using Windows, doesn't always work to close the Frontastic CLI. To close the connection, you'll need to type exit. If it doesn't work the first time, type exit again and this should close the connection.

Yarn install Chromium error on M1 Mac

After running yarn install on an M1 Mac, you'll probably encounter some issues.

If you get the error below:

The chromium binary is not available for arm64:
If you are on Ubuntu, you can install with:

 apt-get install chromium-browser

            throw new Error();

You'll need to install Chromium manually on your local machine. You can do this using Homebrew:

brew install chromium

If after running Chromium, your M1 mac says that it doesn't allow third-party apps to be open, you might need to give Chromium permission to do so.

Go to your System Preferences then Security & Privacy  and then General. Select Allow apps downloaded from Anywhere.
If the Anywhere option isn't visible, run the following command in your terminal and re-open the security screen to find the anywhere option.

sudo spctl --master-disable

Try to launch Chromium again after this. If opening Chromium still fails because “Chromium is damaged and can't be opened,” open the terminal and run the following command:

xattr -cr /Applications/

After retrying to open Chromium, it should open without the error message.

The next step is to modify your .zshrc file and add the following 2 lines of code to skip future Chromium installs:

export PUPPETEER_EXECUTABLE_PATH=`which chromium`

The final step is to close your terminal and reopen it. Then complete the yarn install as described in the Frontastic CLI article.

If you ran yarn install before and encountered the error, you might want to run the commands below to remove the existing node modules, package-lock.json, and cache from the project:

rm -rf node_modules/
rm -rf package-lock.json
rm -rf .cache

Node-darwin-arm64 error on M1 Mac

You might get the below error when running yarn install on a M1 Mac:

Error: Cannot find module 'node-darwin-arm64/package.json

The key is to install Rosetta and to re-install Node.js using nvm.

To install Rosetta run the following command in your terminal:

softwareupdate --install-rosetta

To re-install Node.js using nvm, run the following commands in your terminal:

Summary of the steps:

node -v
node -p process.arch
arch -x86_64 zsh
nvm use 16.5.0 && nvm uninstall v16.13.1 && nvm install v16.13.1
Now using node v16.5.0 (npm v7.19.1)
Uninstalled node v16.13.1
Downloading and installing node v16.13.1...
# output here
Now using node v16.13.1 (npm v8.1.2)
yarn install

When running yarn install, you shouldn't see the error.

Windows thinks the CLI is a virus

Sometimes, Windows might think the CLI is a virus. On close, it might delete the .exe and you'll get a message like this:

Couldn't update hosts: fork/exec C:\Users\track\Desktop\frontastic-cli\frontastic.exe: Operation did not complete successfully because the file contains a virus or potentially unwanted software

Or you might get a threat quarantined message.

To change the settings to stop this from happening, follow the steps below:

  1. Go to Windows Security
  2. Select Virus & Threat Protection
  3. Select Protection History
  4. Find the quarantined CLI file (make sure it's the CLI .exe file and not a real threat)
  5. Select Actions
  6. Select Restore

Debugging SSG issues

When the CLI errors because of an SSH connection issue, the first thing to try should be connecting to the sandbox using SSH manually.

On Linux and macOS, this is as easy as running:
ssh [email protected]


On Windows, it's to note that the CLI doesn’t use just any SSH client currently installed on the system. Especially, it doesn’t use the OpenSSH client, which comes with Windows 10 and later by default. This is because mutagen also doesn’t use it, and testing with another client than mutagen would make the test useless.

  • C:\Program Files\Git\usr\bin
  • C:\Program Files (x86)\Git\usr\bin
  • C:\msys32\usr\bin
  • C:\\msys32\\usr\\bin
  • C:\cygwin\bin
  • C:\cygwin64\bin

So when testing the connection manually, make sure to use the SSH client binary in the first path from above which is present at the computer.

This should prompt for the sandboxes SSH password (which can be found in the studio) and after entering that it should give a shell on the sandbox.

Debugging the pull command

If you get errors running frontastic pull, check if the pull script on the sandbox works by directly executing it:

  1. Connect to the current sandbox through SSH (by running frontastic ssh).
  2. Execute cd /var/www/frontastic && /var/www/frontastic/paas/replicator/bin/pull.
    If the direct command runs fine, report it as a problem with the CLI.
    If you get the same error, then there's something wrong with your sandbox. The fastest solution is probably to create a new sandbox.