Chapter 1. Troubleshoot the installation

Symptom: The Loki Operator subscription shows ResolutionFailed status.

Cause: Incorrect channel name or source catalog.

Resolution:

Symptom: After creating the LokiStack custom resource, pods remain in Pending state and never start.

Cause: No StorageClass exists, or the specified StorageClass does not support dynamic provisioning.

Common on: single-node OpenShift deployments and edge clusters.

Resolution:

Symptom: The LokiStack custom resource shows Ready: True, operators are installed, but logs disappear and are not stored or queryable.

Cause: Object storage is not configured or the object storage secret is incorrect.

Resolution:

LokiStack requires two separate types of storage:

See "Configuring object storage for LokiStack" to configure the S3-compatible backend and create the storage secret.

Symptom: The LokiStack shows Ready: True, operators are installed, log collector pods are running, but logs are silently dropped and never appear in queries.

Cause: Missing TLS CA bundle for object storage, or incorrect object storage permissions.

Resolution:

Symptom: The ClusterLogForwarder custom resource shows Ready: True, but no logs appear in LokiStack or other HTTP-based sinks. The collector logs show the following error:

error:0A000086:SSL routines:tls_post_process_server_certificate:certificate verify failed:ssl/statem/statem_clnt.c:2123:: self-signed certificate in certificate chain

Cause: The tls.ca block is missing or incorrect in the ClusterLogForwarder output configuration.

Resolution:

Add the tls.ca block to your ClusterLogForwarder output:

spec:
  outputs:
  - name: default-lokistack
    type: lokiStack
    tls:
      ca:
        configMapName: logging-loki-gateway-ca-bundle
        key: service-ca.crt

The Loki Operator creates the logging-loki-gateway-ca-bundle ConfigMap automatically. For self-signed certificates on external outputs, reference your custom CA ConfigMap.

Symptom: The collector logs show 429 Too Many Requests responses and the collector retries requests.

Cause: The collector is sending logs faster than the LokiStack or destination sink can process them.

Common during:

Resolution:

This condition resolves automatically. The collector retries with exponential back-off. On a 1x.demo LokiStack, the backlog typically clears within several minutes. Larger LokiStack sizes clear backlogs faster.

Symptom: After installing operators and creating LokiStack, the Logs tab does not appear under Observe in the web console.

Cause: The Cluster Observability Operator is not installed, or the UIPlugin custom resource was not created.

Resolution:

Both steps are required to enable the web console logs interface:

Symptom: The ClusterLogForwarder status shows Ready: True but no logs appear in LokiStack or destination sinks.

Cause: The ClusterLogForwarder validation passes even when the collector cannot connect to LokiStack. The most common cause is missing TLS CA configuration.

Resolution: