Elastic Agent doesn’t start

If your Elastic Agent fails to start, it’s often due to configuration or environment-related issues. This guide walks you through the most common root causes and how to resolve them.

Elastic Agent fails to start or crashes immediately after launch.

Possible causes include:

• Invalid YAML configuration, including syntax errors or unsupported fields
• Port binding conflicts, for example ports 4317 or 4318 already in use
• Missing or misconfigured required components, such as receivers or exporters
• Incorrect permissions or volume mounts in containerized environments

The solution depends on your Elastic Agent's setup:

• Standalone
• Kubernetes

If you're deploying the Elastic Agent in a standalone configuration, try to:

• Validate configuration syntax

  Run the following to validate your configuration without starting the Collector:

  otelcol validate --config=/path/to/otel-collector-config.yaml
  

  This checks for syntax errors and missing components.

• Check logs for stack traces or component errors

  Review the Collector logs for error messages indicating configuration problems. Common examples include:

  error initializing exporter: no endpoint specified
  

  Most critical issues, such as missing or invalid exporters or receivers, will be logged.

  To increase verbosity, run:

  ./otelcol --set=service.telemetry.logs.level=debug
  

  This is especially helpful for diagnosing configuration parsing issues or startup errors. For more information on enabling debug logging, refer to Enable debug logging.

• Confirm required components are defined

  Ensure service.pipelines references valid receivers, processors, and exporters. The minimal configuration depends on your use case:

  • For logs: filelog receiver, resourcedetection processor, elasticsearch exporter

  • For traces: otlp receiver, elastictrace and elasticapm processors, elasticsearch exporter

  • For managed OTLP endpoint: use relevant receivers and export using the otlp exporter

  Refer to Default configuration of the Elastic Agent (Standalone) for full examples for each use case.

• Check for port conflicts

  By default, Elastic OpenTelemetry uses:

  • 4317 for OTLP/gRPC
  • 4318 for OTLP/HTTP

  Run this to check if a port is in use:

  lsof -i :4317
  

  If needed, adjust your configuration or free up the port. For network connectivity issues, refer to Connectivity issues.

If you're deploying the Elastic Agent using the Elastic Helm charts, try to:

• Double-check your custom values.yaml or --set overrides for typos or missing fields.

• Ensure volume mounts are correctly defined if you're using custom configuration files.

• If you're managing the Collector through Fleet, confirm that the policy includes a valid configuration and hasn't been corrupted or partially applied.

• Use kubectl logs <collector-pod> to get Collector logs and diagnose startup failures.

• Check the status of the pod using:

  kubectl describe pod <collector-pod>
  

  Common issues include volume mount errors, image pull failures, or misconfigured environment variables.

If the Collector starts but no data appears in Kibana, refer to No data visible in Kibana for additional troubleshooting steps.

• Collector configuration documentation
• Elastic Stack Kubernetes Helm Charts