Docker troubleshooting for InfluxDB v1 Enterprise
This guide covers common Docker-specific issues and solutions when running InfluxDB v1 Enterprise in containers.
Common Docker issues
License key issues
Problem: Container fails to start with license error
Symptoms:
license key verification failed
Solution:
- Verify your license key is valid and not expired
- Ensure the license key environment variable is set correctly:
-e INFLUXDB_ENTERPRISE_LICENSE_KEY=your-actual-license-key
- If nodes cannot reach
portal.influxdata.com
, use a license file instead:-v /path/to/license.json:/etc/influxdb/license.json -e INFLUXDB_ENTERPRISE_LICENSE_PATH=/etc/influxdb/license.json
Network connectivity issues
Problem: Nodes cannot communicate with each other
Symptoms:
- Meta nodes fail to join cluster
- Data nodes cannot connect to meta nodes
influxd-ctl show
shows missing nodes
Solution:
- Ensure all containers are on the same Docker network:
docker network create influxdb # Add --network=influxdb to all container runs
- Use container hostnames consistently:
# Use hostname (-h) that matches container name -h influxdb-meta-0 --name=influxdb-meta-0
- Verify network connectivity between containers:
docker exec influxdb-meta-0 ping influxdb-meta-1
Problem: Cannot access InfluxDB from host machine
Symptoms:
- Connection refused when trying to connect to InfluxDB API
- Client tools cannot reach the database
Solution: Expose the HTTP API port (8086) when starting data nodes:
docker run -d \
--name=influxdb-data-0 \
--network=influxdb \
-h influxdb-data-0 \
-p 8086:8086 \
-e INFLUXDB_ENTERPRISE_LICENSE_KEY=your-license-key \
influxdb:data
Configuration issues
Problem: Custom configuration not being applied
Symptoms:
- Environment variables ignored
- Configuration file changes not taking effect
Solution:
For environment variables, use the correct format
INFLUXDB_$SECTION_$NAME
:# Correct -e INFLUXDB_REPORTING_DISABLED=true -e INFLUXDB_META_DIR=/custom/meta/dir # Incorrect -e REPORTING_DISABLED=true
For configuration files, ensure proper mounting:
# Mount config file correctly -v /host/path/influxdb.conf:/etc/influxdb/influxdb.conf
Verify file permissions on mounted configuration files:
# Config files should be readable by influxdb user (uid 1000) chown 1000:1000 /host/path/influxdb.conf chmod 644 /host/path/influxdb.conf
Data persistence issues
Problem: Data lost when container restarts
Symptoms:
- Databases and data disappear after container restart
- Cluster state not preserved
Solution: Mount data directories as volumes:
# For meta nodes
-v influxdb-meta-0-data:/var/lib/influxdb
# For data nodes
-v influxdb-data-0-data:/var/lib/influxdb
Resource and performance issues
Problem: Containers running out of memory
Symptoms:
- Containers being killed by Docker
- OOMKilled status in
docker ps
Solution:
Increase memory limits:
--memory=4g --memory-swap=8g
Monitor memory usage:
docker stats influxdb-data-0
Optimize InfluxDB configuration for available resources.
Problem: Poor performance in containerized environment
Solution:
- Ensure adequate CPU and memory allocation
- Use appropriate Docker storage drivers
- Consider host networking for high-throughput scenarios:
--network=host
Debugging commands
Check container logs
# View container logs
docker logs influxdb-meta-0
docker logs influxdb-data-0
# Follow logs in real-time
docker logs -f influxdb-meta-0
Verify cluster status
# Check cluster status from any meta node
docker exec influxdb-meta-0 influxd-ctl show
# Check individual node status
docker exec influxdb-meta-0 influxd-ctl show-shards
Network troubleshooting
# Test connectivity between containers
docker exec influxdb-meta-0 ping influxdb-data-0
docker exec influxdb-meta-0 telnet influxdb-data-0 8088
# Check which ports are listening
docker exec influxdb-meta-0 netstat -tlnp
Configuration verification
# Check effective configuration
docker exec influxdb-meta-0 cat /etc/influxdb/influxdb-meta.conf
docker exec influxdb-data-0 cat /etc/influxdb/influxdb.conf
# Verify environment variables
docker exec influxdb-meta-0 env | grep INFLUXDB
Best practices for Docker deployments
- Use specific image tags instead of
latest
for production deployments - Implement health checks to monitor container status
- Use Docker Compose for complex multi-container setups
- Mount volumes for data persistence
- Set resource limits to prevent resource exhaustion
- Use secrets management for license keys in production
- Implement proper logging and monitoring
- Regular backups of data volumes
Getting additional help
If you continue to experience issues:
- Check the general troubleshooting guide
- Review InfluxDB Enterprise logs
- Contact InfluxData support with:
- Docker version and configuration
- Container logs
- Cluster status output
- Network configuration details
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB Enterprise and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support. Customers using a trial license can email trial@influxdata.com for assistance.