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.