Table of Contents

Troubleshooting

You will find on this page all the errors that you can potentially encounter when installing or updating prerequisites and the Neos tool.

Failed to create shell shim for tool 'GroupeIsa.Neos.Console'

This error may occur when the Neos tool is updated.

  1. Check that there is no neos.exe process running.

  2. Uninstall the tool with the following command:

dotnet tool uninstall GroupeIsa.Neos.Console --global

  1. Verify that the folder C:\Users\[USER]\.dotnet\tools\.store\groupeisa.neos.console and the executable C:\Users\[USER]\.dotnet\tools\neos.exe no longer exist.

  2. Reinstall the tool with the following command:

dotnet tool install GroupeIsa.Neos.Console --global --ignore-failed-sources --no-cache --interactive --verbosity minimal

Failed to run dotnet tool restore command

This error may occur when trying to run a cluster with a specific neos version defined in the dotnet-tools.json file.

Sometimes this is due to a corrupted nuget cache, you can clean it with the following command :

dotnet nuget locals all --clear

Error "0x8a15005e : The server certificate did not match any of the expected values." during neos setup

This error may occur during the execution of the neos setup command when Neos installs components using WinGet.
Neos now uses the winget source explicitly during these installations, but if you need to rerun a failed command manually, add --source winget.

Example :
The following error is displayed in the console :

10:06:21 INF GroupeIsa.Neos.Console.Setup.DaprSetup - winget install Dapr.CLI --disable-interactivity --accept-source-agreements --accept-package-agreements --version 1.16.5 --source winget
Échec lors de la recherche de la source : msstore
Une erreur inattendue s'est produite lors de l'exécution de la commande :
0x8a15005e : The server certificate did not match any of the expected values.

Les packages suivants ont été trouvés parmi les sources de travail.
Spécifiez l’un d’entre eux à l’aide de l’option --source pour continuer.
Nom      ID       Source
------------------------

Execute the following command :

winget install Dapr.CLI --disable-interactivity --accept-source-agreements --accept-package-agreements --version 1.16.5 --source winget

The first generation is stuck after 2 minutes of waiting

If the first generation is stuck after 2 minutes of waiting and you have the Kaspersky antivirus installed, check if there is a node.exe process with the npm install command line running. If it is the case, it's probably because Kaspersky is blocking the client dependencies download.

If this is the case, you must whitelist some urls:

https://*.blob.core.windows.net
https://*.visualstudio.com

The application does not display and a "The requested address is not valid in its context (localhost:0)" appears in the logs

This can be caused by other errors that appear sooner in the logs and prevents the application from working properly. Correcting all the previous errors should make this error disappear.

The manager does not open when running neos run

If the manager does not open after neos run, first rerun:

neos setup

This is the first thing to try when the backend seems to start but the browser does not open on the manager page, or when the manager URL returns an error even though neos run has started.

Running neos setup is useful because it rechecks the local prerequisites used by neos run and repairs common local environment issues, especially on Windows:

  • it recreates the development certificate if the current one is invalid or was created by another tool;
  • it reassociates that certificate with HTTP.sys;
  • it rechecks local tooling installed by setup such as Dapr and Redis.

This problem is often caused by a local machine state that became inconsistent after a Neos update, a framework version switch, or another tool changing the local development certificate configuration.

The server is running without errors but I received a 503 HTTP error.

This error may occur on Windows with the Http.sys web server (default web server on Windows).
https://+:443 and http://+:80 may be reserved by the system.
You can check the URL reservation with the command netsh http show urlacl.

  • If this command shows the line Reserved URL: http://+:80/, you have to delete this reservation with the command :
    netsh http delete urlacl url=http://+:80/

  • If this command displays the line Reserved URL: https://+:443/, you have to delete this reservation with the command :
    netsh http delete urlacl url=https://+:443/

Note

This command has an immediate effect, there is no need to restart neos.

Redis errors

Failed to start Redis service

If the Redis server does not start in neos setup or neos run, you can carry out the following steps to resolve the problem.

If you have run a Neos cluster in a version prior to 2.5.0, Redis could be started in WSL instead of via Memurai.

First, try to stop the Redis service with the following commands:

wsl -u root sudo service redis-server stop

neos setup

If the problem persists, you can try purging WSL and reinstalling Neos:

wsl -u root apt-get purge --auto-remove redis-server

neos setup

Another Redis instance is running on the same machine / port 6379 already in use

If you already have a Redis instance running on the same machine at localhost:6379 or the port is in use by another existing process, you can configure the cluster to use another Redis instance.

This is done in the cluster configuration file by setting the RedisHost property.

Dapr warnings

Dapr - dropping expired pub/sub event

This warning can occurs when the Redis instance is corrupted. To clean the Redis instance, you can use the following command :

memurai-cli FLUSHDB # On windows
redis-cli FLUSHDB # On Linux / MacOS

Dapr version mismatch when switching framework versions

Starting from framework versions 3.0.2, 2.5.10, and 2.4.10, Dapr has been upgraded from version 1.13 to version 1.16. When switching between framework versions that require different Dapr versions, you may encounter compatibility issues.

Downgrading to Dapr 1.13

If you need to work with a previous framework version that requires Dapr 1.13, you must manually reinstall Dapr by running the following commands in order:

  1. Uninstall the current Dapr runtime
dapr uninstall
  1. Uninstall the Dapr CLI
winget uninstall --exact --id Dapr.CLI
  1. Reinstall Dapr with the version configured in your cluster
neos setup

Upgrading back to Dapr 1.16

When returning to a framework version that requires Dapr 1.16, remember to run:

neos setup

This will reinstall Dapr with the correct version for the current framework.