Skip to content

Troubleshooting

quinectl prints each error on a line that starts with error:, often followed by what to change. Add -v (or -vv) to up and down for more detail while they run.

Configuration and environment

What you see What to do
error: quine.licenseKey references ${QE_LICENSE_KEY} but it is not set (or is empty) in the environment Export the variable in the shell you run quinectl from. Not every field reads ${NAME}; see Values from the environment.
error: pulling <image> from registry.license.thatdot.com needs quine.customerId Export QE_CUSTOMER_ID and set customerId: ${QE_CUSTOMER_ID} (or the Novelty pair). quinectl needs it only to pull an image from the thatDot registry.
quine.realm is used only under services.auth: keycloak Remove the auth fields after switching to auth: none. See Turning auth off.
A message naming a missing required field Add the field. The six required choices are listed in Configure quinectl.
error: no quinectl.yaml in <directory> — run 'quinectl init' to create one Run quinectl from your project directory, or create a file there with quinectl init (--edition oss for Quine OSS). up, status, token, generate-quine-conf, cass-reset and kafka-reset need one.

Starting services and products

What you see What to do
up fails before starting anything because Docker isn't reachable Start Docker. docker info should succeed. If your engine isn't the default one, set DOCKER_HOST.
The product image pull is refused Check QE_CUSTOMER_ID and QE_LICENSE_KEY (or the Novelty pair) belong together and the license hasn't expired.
up reports the product exited while starting Read the log it names, logs/<product>/member-<n>.log. A rejected license key shows there. If the product has run in this directory before, a rejected key may not stop it, and up succeeds, so check the log after changing a key.
error: converging <service>: <service> container <name> exited (code <n>) before becoming ready A service container such as Keycloak or Cassandra stopped on start. The error ends with its last log lines; docker logs <name> shows the rest.
A port is already in use Another program, or another project, has it. For a product's port, change quine.port or novelty.port, or use quinectl init --agent. For a shared service's port, stop the program using it: every project uses that port.

Several projects on one machine

What you see What to do
A warning that a keyspace, realm or topic is also used by another directory Give this project its own quine.keyspace, quine.realm or Kafka namespace. See Multi-tenancy.
error: refusing --rm: this directory still has members that may be running Run quinectl down first, then quinectl down --rm. See Stopping and removing.
error: refusing --rm: … are still in use by other tenants Other projects still use the shared services the error lists; quinectl's errors call a project a tenant. See Stopping and removing.

Resetting data

What you see What to do
An error about a topic's partition count Partitions can't change after a topic exists. Run quinectl kafka-reset, then up.
A deleting command exits 2 asking for --yes There was no terminal to ask. Pass --yes if you mean it. down and gc can be previewed first with --dry-run; cass-reset and kafka-reset can't.

Sign-in and tokens

What you see What to do
A secure connection error at a localhost address after trusting the certificate Use Local Hostnames, or 127.0.0.1 in place of localhost. See Trusting the local certificate.
The browser warns about the sign-in page's certificate Run quinectl trust on macOS, or import ~/.quinectl/state/certs/ca.pem. See Trusting the local certificate.
Signing in to one product signs you out of the other Open each product at the address up prints, one on localhost and one on 127.0.0.1.
401 with Missing session cookie or access token. from the REST API Add -H "Authorization: Bearer $(quinectl token)". Tokens last five minutes.
error: --user "…" is not one of the configured sample users Use one of the usernames the error lists, or that quinectl status prints.

Metrics

What you see What to do
Grafana shows a member dropping in and out Collecting its metrics is timing out. Raise scrapeInterval and scrapeTimeout.
error: grafana port 3001 differs from the shared quinectl-grafana's port 3000 Prometheus and Grafana are shared, so their ports apply to every project. Use the port the error names. See Sharing with other projects.
warning: replacing shared quinectl-grafana (config drift) or (image drift) Two projects disagree on a Grafana image, sign-in setting or grafanaPublicUrl, and the last up wins. Make them match. See Sharing with other projects.

Getting more help

For problems getting quinectl itself, see Get quinectl. When you contact thatDot support, include the output of quinectl version and the command you ran with -vv.