Troubleshooting

Start with ldev doctor, then ldev logs diagnose for detailed diagnosis.

---

Startup Issues

Docker not running

[FAIL] Docker Daemon: docker CLI is available but the daemon is not responding

Fix: Start Docker Desktop (or sudo systemctl start docker on Linux).

Port already in use

[WARN] HTTP Port: localhost:8080 is already in use

Fix: Change port in docker/.env:

LIFERAY_HTTP_PORT=8181

Low host memory

[WARN] Host Memory: 4.0 GiB is below recommended 8 GB

Fix: Allocate more RAM to Docker, or close other apps. Minimum 8 GB required.

Activation key invalid or missing

[FAIL] Activation Key: path does not exist

Fix:

export LDEV_ACTIVATION_KEY_FILE=/path/to/activation-key-dxp-*.xml
ldev start

Portal not starting (timeout)

Health wait: liferay health endpoint not responding

Fix: Check logs:

ldev logs follow --service liferay     # Stream logs
ldev logs diagnose                      # Full diagnosis

Common causes:

• Activation key expired or invalid
• Not enough memory/disk
• Port conflict
• Corrupted data directory: ldev env clean then ldev start

---

OAuth & Authentication

OAuth install fails

Cause: Portal setup wizard not completed or wrong credentials.

Fix:

1. Open http://localhost:8080
2. Log in with test@liferay.com / test
3. Complete setup wizard
4. Run: ldev oauth install --write-env

Portal check fails: "401 Unauthorized"

Cause: OAuth2 credentials missing or invalid.

Fix:

ldev oauth install --write-env     # Re-register apps
ldev oauth admin-unblock           # Clear password-reset gate
ldev portal check                  # Retry

"Portal requires first login"

Cause: Setup wizard not completed.

Fix: Manually complete setup at http://localhost:8080, then retry OAuth install.

---

Database & Import Issues

ldev db import times out or fails

Cause: Database too large or corrupted backup.

Fix:

ldev db import --verbose           # See what's happening
# If it fails, check post-import script syntax:
cat docker/sql/post-import.d/010-adapt-local-db.sql | head -20

ldev db download fails (LCP credentials)

Cause: Invalid LCP_PROJECT or LCP_ENVIRONMENT in docker/.env.

Fix: Verify in docker/.env:

LCP_PROJECT=my-actual-lcp-project     # Check spelling
LCP_ENVIRONMENT=staging               # dev, staging, or prd

Database corrupted after import

Cause: Post-import SQL script error or data corruption.

Fix: Reimport from backup:

ldev env clean                 # Delete data
ldev db download               # Re-download
ldev db import                 # Re-import

---

Deployment Issues

Deploy completes but changes don't appear

Cause: Bundle stuck, or app not reloaded.

Fix:

ldev deploy prepare               # Build only
ldev osgi status                  # Check bundle state
ldev env restart                  # Full restart

Deploy fails with "artifact not found"

Cause: Build failed or wrong module name.

Fix:

ldev deploy prepare               # Test build without deploying
# Check error output and fix build

Deploy reports partial hot deploy

Cause: One or more artifacts could not be copied to the running container.

Fix:

ldev deploy prepare               # Rebuild artifacts
ldev deploy module foo-web        # Retry module deploy

If output says that only some artifacts were deployed, treat it as a failed deploy and use the reported artifact errors to fix the failing module/theme first.

Deploy cache lock timeout

Timed out waiting for deploy cache lock

Cause: Another deploy command is running at the same time, or a previous deploy was interrupted.

Fix:

1. Wait for the other deploy to finish, then retry.
2. If no deploy is running, run ldev env restart and retry the deploy command.

---

Portal Issues

Elasticsearch not responding / reindex stuck

Cause: Elasticsearch OOM or corrupted indices.

Fix:

ldev env clean                        # Clean all data
ldev start                            # Fresh start
ldev portal reindex speedup-on         # Reindex

Search queries return no results

Cause: Content not indexed.

Fix:

ldev portal reindex speedup-on         # Full reindex
ldev portal search indices            # Verify indices exist

Portal shows old data

Cause: Cache not cleared.

Fix: Restart Liferay:

ldev env restart

---

Worktree Issues

ldev worktree setup --with-env fails

Cause: Not enough disk space or main environment still running.

Fix:

ldev status              # Check main environment
ldev stop                # Stop main if running
ldev worktree setup --name task-123 --with-env

Worktree takes too much disk space

Cause: Multiple worktrees with separate Docker data.

Fix:

ldev worktree gc                  # Clean unused worktrees
ldev worktree clean --force       # Delete specific worktree

---

Quick Diagnostic Commands

When stuck, run:

ldev doctor                    # Check prerequisites
ldev status                    # Show container status
ldev logs diagnose             # Full diagnosis
ldev context --json            # Current configuration
ldev portal check              # Portal health

For verbose output:

ldev logs follow --service liferay      # Stream Liferay logs
ldev logs follow --service elasticsearch # Stream Elasticsearch logs

---

Still Stuck?

1. Run: ldev logs diagnose (provides full context)
2. Check: FAQ for common platform and usage questions
3. See: Commands Reference for detailed command options
4. Explore: ldev <command> --help for all flags

---

See Also

• First Incident — Practical diagnosis flow
• Configuration — Environment variables
• FAQ — Common platform and workflow questions