Troubleshooting

DevNote update this with new discoveries regarding configurations

Ports are not available

When you’re running various services on your machine, it’s common that the ports are already in use. You will see something like this:

Cannot start service server: Ports are not available: listen tcp 127.0.0.1:18080: bind: address already in use

If you see this error, you can change the port number to something between 1024 and 65535. You can also replace the value for services.server.ports in docker-compose.yaml to ["80"], and Docker will pick an available port for you.

⚠️ Make sure also to change the port everywhere else.

WebSocket connection failing with Nginx

If the WebSocket connection is failing to establish, you might need to enable Nginx WebSocket proxying.

You can find detailed instructions and further examples in the Nginx documentation.

Inside your nginx.conf file (by default, it is located inside the /etc/nginx directory), add the following lines to the server configuration section.

Make sure to adjust the location if you’ve defined a custom configuration that affects the base path.

location /api/websocket {
  proxy_pass http://server:80;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "Upgrade";
  proxy_set_header Host $host;
}

Connection to Corredor server

You might see one or more connection refused errors in server container logs (docker-compose logs -f server):

{"level":"error","ts":1608125024.4714684,"logger":"corredor","caller":"corredor/service.go:427","msg":"could not load corredor server scripts","error":"rpc error: code = DeadlineExceeded desc = latest balancer error: connection error: desc = \"transport: Error while dialing dial tcp 172.23.0.2:80: connect: connection refused\"","stacktrace":"github.com/cortezaproject/corteza-server/pkg/corredor.(*service).loadServerScripts\n\t/drone/src/pkg/corredor/service.go:427"}

If there are a couple of errors when the server is starting up, that’s ok. Sometimes it takes more time to start up Corredor server, and Corteza server can not yet connect to it.

If the problem persists, and you can see Corredor state as healthy, verify the changes you might have made to the configuration.

Network proxy declared as external

ERROR: Network proxy declared as external, but could not be found. Please create the network manually using `docker network create proxy` and try again.

Make sure your nginx-proxy service is up and running before running Corteza.

Blank screen on `/auth` with the "state does not match" error in the browser console

The state does not match error usually occurs in the development environment or where the Corteza server is frequently restarted.

The authentication state which is carried through the user authentication flow is not persistent and will perish on server restart. If the error occurs and persists on the production environment, verify your AUTH_SESSION_* .env settings (in case you have modified them).

Stuck on login screen after providing valid credentials

Please note that some deployments (like with Docker) might not have all configuration available for valid autoconfiguration. Check what how the cookies are sent in the response headers on login.

Please note that examples below have an abbreviated session value.

Broken configuration, user is stuck on login screen

set-Cookie:
    session=MTYzODQ...tCLvO_DHhw==;
    Path=/auth;
    Domain=e3a47cb50c17; (1)
    Expires=Sun, 27 Nov 2022 10:13:08 GMT;
    Max-Age=31104000;
    HttpOnly

1	Set of random characters where the domain or hostname should be represent Docker container ID (and hostname). Setup like this require `DOMAIN` variable to be set (for example. `DOMAIN=localhost:8080`). Do not forget to recreate your server container after the change.

Valid cookie example

set-Cookie: (1)
    session=MTYzODQ...tCLvO_DHhw==;
    Path=/auth;
    Expires=Sun, 27 Nov 2022 12:58:01 GMT;
    Max-Age=31104000;
    HttpOnly

1	When you provide `DOMAIN` option like instructed in the example above, you’ll notice that "Domain" flag on the cookie is missing. Corteza removes it when you use port in the domain.

Valid example of a cookie on a secure host

set-cookie:
    session=MTYzODQ...tCLvO_DHhw==;
    Path=/auth;
    Domain=corteza.example.org;
    Expires=Fri, 03 Dec 2021 12:58:46 GMT;
    Max-Age=86400;
    HttpOnly;
    Secure (1)

1	Note the "Secure" cookie flag. This cookie will be sent back to the server only if server is on secure domain (HTTPS). If you used `HTTP_SSL_TERMINATED` or `LETSENCRYPT_HOST` options Corteza will assume that it is served on a secured domain.

Further troubleshooting

If you’re continuing to have issues with Corteza, we encourage you to contact other users on our community server. You’ll more than likely find someone who can help you out. You can also open an issue on our cortezaproject/corteza-server GitHub repository.