Troubleshooting#

Start with the two things the UI shows for a new install: the getting-started checklist and the ingestion card. Then the pods and core's log:

kubectl get pods -n hyvop
kubectl logs deploy/hyvop-core -n hyvop
kubectl logs deploy/hyvop-ingestor-aws -n hyvop

The getting-started checklist#

The "Getting started" card shows four steps, each done, running, failed or not yet started. It disappears when all four are done. What each step says and what to do:

Step	State and message	What to do
Connect a cloud account	not yet: "One account on AWS, Azure or GCP"	Connect one: AWS, Azure, GCP
	failed: "The state of the collections could not be read from core"	Reload; if it stays, read core's log and check that the pod is ready
First collection	running: "The resources of the account are being read"	Wait a few minutes. The page follows it
	failed: "Core cannot reach the ingestor"	See "The ingestor cannot be reached" below
	failed: "The last collection failed: <reason>. It is tried again by itself."	Read the reason; it is the ingestion card's too
Detectors	not yet: "No detector is installed yet", or "Every installed detector is switched off"	Install some from the catalogue, or switch one on (an administrator)
First detection run	running: "Detection runs after each collection and every night"	An administrator can start it now from the installed detectors. Findings are under Inefficiencies

The ingestion card#

Integrations shows, for the connected account, the last and next run of each collection: Inventory, Metrics, Billing and "Resources for ownership". A run is running now, last run <when>, last failed <when> or not run yet; a completed run shows its row count. A failed run shows its reason, and a run that otherwise went through lists the services that failed inside it.

Default schedules: inventory every 4 hours, metrics every 2 hours, billing nightly at 02:00, the ownership copy every 15 minutes, pricing on Sunday at 23:00. A newly connected account is collected at once. Findings that rest on metrics wait until a resource has 7 or 28 days of history, so a new install finds little in its first days.

Common failures#

The ingestor cannot be reached#

The card says "The ingestor cannot be reached from core right now; scheduled collections will fail until it is." Check:

The ingestor's pod is running and ready (kubectl get pods -n hyvop). The Azure and GCP ingestors do not exist until ingestors.azure.enabled / ingestors.gcp.enabled is set.
Core and the ingestor are of the same release. Core calls the ingestor over TLS; an older ingestor image that does not listen with TLS needs ingestors.<cloud>.tls: false (upgrade.md).
A changed authority: restart core after changing internalTls.existingSecret.
The shared secret between core and the ingestors (hyvop-ingestor-secrets, key shared-secret) is the same for both.

A region is not enabled#

"<n> regions are not enabled for this account and were not scanned." This is not a failure: AWS accounts do not have every region switched on, and the scan skips the ones that are off. Items a scan could not read are listed as "Left out: <service> in <region>: <reason>".

No price list#

Savings and cost estimates need prices. Prices are read by the ingestor from the cloud's public price lists when core asks for a pricing collection: with the first collections when an account is connected, then weekly. If the first collection failed, an administrator can ask again with POST /api/v1/ingest/pricing. The ingestors must reach the price lists on port 443. An install with no internet access gives the AWS ingestor a bundle of price lists on disk: ingestors.aws.env.PRICING_SOURCE_DIR (air-gapped.md).

AI is off#

"AI features are off until a model provider is configured" is the normal state of a new install. Set core.env.AI_PROVIDER and a key: models.md. If AI is on and the assistant still fails, check that networkPolicy.egress.core.internet allows the model's address (a model on a private address needs networkPolicy.egress.extraCidrs).

No approval e-mail arrives#

First: a new install has no mail relay, and then nothing is sent by design; each approver is reported as not mailed. Set core.mail.host (mail.md) or give a relay in the settings screen. If one is set:

Core cannot reach it. A relay listens on 587 or 25 and the network policy allows the internet on 443 only: put the relay's addresses in networkPolicy.egress.mailCidrs.
The relay refuses the sender. Set core.mail.from to an address it hosts.
The sign-in is refused. Check core.mail.username and the Secret key mail-password. The test message in the settings screen answers in the mail server's own words.
No link can be made because core.env.FRONTEND_URL is not the public address.
The approver has no address in the ownership contract, or the plan is not yet awaiting review.
The message was sent and is in a spam folder. A link is valid for 7 days unless core.mail.approvals.linkValidity says otherwise, and a reminder follows every 3 days, twice at most.

Limits of the Community Edition#

A scan that stops at 1,000 resources says so above every screen. A second cloud account is refused while the first is on, a fourth active policy cannot be switched on, and Jira and ServiceNow are refused with the plan that has them (editions.md). Single sign-on set in a Community install does not stop it: people sign in with their e-mail and password, and the sign-in page says that the provider is not in the edition.

Cost is missing#

AWS: no billing export has been delivered yet (the first delivery takes about 24 hours), or the bucket and prefix in the screen do not match the export (connect-aws.md).
Azure: the subscription was connected without a cost export; core does not ask for billing then (connect-azure.md).
GCP: the connection names no billing export table; core asks for billing only when it does (connect-gcp.md).

"Too many failed sign-ins": core refuses sign-in for an account or an address after too many failures and says how long to wait.
The first-account screen asks for a code: the install was given core.setupCode; read it with the command in install.md.
On a claimed install, new accounts come by invitation only.
The browser reports a blocked request from an address other than the install's own: name that origin exactly in core.env.CORS_ALLOWED_ORIGINS (a wildcard is refused).

Core does not start#

A second core pod waits and logs that another instance holds the data-lake migration lock: two pods starting together on an empty ClickHouse take turns; this is normal and ends by itself. If the first has died, the waiting pod fails after core.env.DATALAKE_MIGRATION_LOCK_WAIT (5m as shipped). Wait for the first pod to be ready and start the other again, or give it longer.
"Core does not start while a stored value is under a key it was not given": its log names the table and the key's id. Give the old key in core.env.HYVOP_PREVIOUS_DATA_KEYS (backup-and-restore.md).
After an upgrade from a chart that ran pods as root, a volume may not be writable by the new user: hand it over with chown once (PostgreSQL 70, ClickHouse 101), or set fsGroup where the volume driver honours it.
helm refuses with a message naming a value: the values are checked against the schema, and a provider named with no key stops the install.

"It is not your turn to answer this plan yet"#

Approval follows the plan's chain (core.approvals.order, chain as shipped): the approvers answer one stage after the other and an answer out of turn is refused with this sentence and the name of the person the plan waits for. Nothing is broken; the person asked first has to answer, or be escalated after core.approvals.stepTimeout. Set core.approvals.order: any to let every required approver answer at once. See approvals.md.

Pods stay Pending or cannot pull#

Pending with an unbound volume claim: the cluster has no default storage class. Set global.storageClass.
ImagePullBackOff: the registry needs a login (global.imagePullSecrets), or the images are not where global.imageRegistry points.

A Git server on a private network is refused#

Core calls the address of a Git server (GitHub Enterprise, a self-hosted GitLab) only if it is a public HTTPS address. Name an internal host in core.env.OUTBOUND_ALLOWED_HOSTS (comma-separated host names, *. for a domain).