Skill

doris-debug-deployment

Name: doris-debug-deployment
Author: Apache Software Foundation

troubleshoot Apache Doris deployment failures

Published by Apache Software Foundation Updated Jul 25

Covers Operations Deployment Debugging

Description

Use for Doris FE/BE startup failures, port conflicts, priority_networks misrouting, meta_dir corruption, and ADD/DROP BACKEND issues.

SKILL.md

Deployment & Startup

Causes

ID	Cause	Evidence	Source anchor
A	Port conflict	BE/FE fail to bind; `Address already in use`	`brpc/server.cpp`, `doris_main.cpp`
B	`priority_networks` misconfig	brpc connection refused / wrong interface	`config.cpp`
C	meta_dir / storage_root_path not writable	`Permission denied` / `No such file` at startup	`olap/olap_meta.cpp`
D	FE metadata corruption	FE fails to start after crash; `meta/image.*` errors	`Image.java`, `BDBJEJournal.java`
E	Mixed version cluster	Protocol mismatch in thrift/brpc between FE-BE	`be/src/agent/`, `heartbeat`
F	DNS / hostname resolution	`UnknownHostException`, BE heartbeat to wrong address	`Env.java` frontend host check

10 min triage

# FE status
curl -s "http://$FE:8030/api/bootstrap"
curl -s "http://$FE:8030/api/health"

# BE status
curl -s "http://$BE:8040/api/health"

# Port check
ss -tlnp | grep -E "8030|8040|8060|9030"

-- Cluster membership
SHOW FRONTENDS\G
SHOW BACKENDS\G

Cause A — Port conflict

Default ports (from fe/conf/fe.conf and be/conf/be.conf):

Service	Port	Config key
FE HTTP	8030	`http_port`
BE HTTP	8040	`webserver_port`
BE brpc	8060	`brpc_port`
FE MySQL	9030	`query_port`
FE Edit log	9010	`edit_log_port`

# Kill stale process on target port
fuser -k 8060/tcp  # BE brpc
# Then restart BE

Cause B — priority_networks

The most common cause of "BE shows Alive=true but brpc fails." priority_networks tells BE which network interface to bind brpc to.

# be.conf — match ONE subnet exactly
priority_networks = 10.0.0.0/24

Check what interface BE actually bound:

curl -s "http://$BE:8040/api/health" | grep -o '"ip":"[^"]*"'

Validation: the IP in SHOW BACKENDS must be reachable from every FE and every other BE on port 8060.

Cause D — FE metadata recovery

# Check FE meta directory
ls -la fe/doris-meta/image/
ls -la fe/doris-meta/bdb/

# If bdb is corrupt and this is a follower/observer:
# 1. Remove the bad FE from the cluster
# 2. Wipe doris-meta/
# 3. Re-add as a new follower: ALTER SYSTEM ADD FOLLOWER "host:9010"

Never remove doris-meta/ on the last healthy Master FE.

Source

fe/conf/fe.conf — port defaults
be/src/common/config.cpp — priority_networks
be/src/service/doris_main.cpp — BE startup
fe/.../master/Env.java — FE bootstrap
fe/.../journal/bdbje/BDBJEJournal.java

More skills from the doris-skills repository

View all 14 skills

SkillTagsUpdated

More from Apache Software Foundation

View publisher

SkillTagsUpdated