Troubleshooting

In case you are experiencing issues while setting up or using Corteza you can use the following tools and knowledge bases to help you resolve your issue.

Corteza introduces a Corteza Server Web Console which provides an easy way to access important information such as server logs. The web console can be used to try and pinpoint what is causing the issue.

If you are unable to resolve the issue, you can reach out to the community on our forum.

Ports are not available

When running various services on your machine, it’s common that the ports are already in use. You 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 a number between 1024 and 65535. You can also replace the value for services.server.ports in docker-compose.yaml to ["80"], and Docker then picks an available port for you.

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;

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;
}

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

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.

$ docker network create proxy

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 auto-configuration. Check what 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	A set of random characters where the domain or hostname should represent the Docker container ID (and hostname). Setup like this requires `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, 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 is sent back to the server only if server is on secure domain (HTTPS). If you used `HTTP_SSL_TERMINATED` or `LETSENCRYPT_HOST` options, Corteza assumes that it is served on a secured domain.

Further Troubleshooting

If you continue 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.

SMTP not Working

You can use the corteza-server auth test-notifications command to verify that your SMTP configuration is working correctly. The command sends a test email to the provided email address.

corteza-server auth test-notifications your-email@example.tld

Depending on your provider, the email can take different amounts of time to be delivered. If you can’t see the email, make sure to check your spam folder and server logs.

Connection and authentication errors look like this:

could not send email: dial tcp [::1]:25: connect: connection refused

Changes to the Default Auth-Client Settings Seem not to have been Applied

Restarting the server is required when an admin modifies default authentication client settings, such as client secret or redirect URIs, because those changes are not applied immediately.