Skip to content

Add ReadMe troubleshooting section for network start issues#1356

Open
mitnick2012 wants to merge 1 commit into
dfinity:masterfrom
mitnick2012:patch-1
Open

Add ReadMe troubleshooting section for network start issues#1356
mitnick2012 wants to merge 1 commit into
dfinity:masterfrom
mitnick2012:patch-1

Conversation

@mitnick2012

Copy link
Copy Markdown

Overview
When icp network start exits with status 101, the terminal output gives no
actionable information. The actual error (e.g. port conflict) is silently written
to a log file that new users have no reason to know exists. This leaves developers
stuck with a cryptic error and no clear path to resolution.

Requirements

  • Document where to find the real error log
  • Cover the most common root cause (port 8000 already in use)
  • Provide a concrete fix for the Docker port conflict case
  • The fix must get icp network start -d running successfully

Considered Solutions

  1. Improve the CLI output to surface the log file contents directly in the terminal
    instead of just reporting exit status 101 — this would be the ideal long-term fix
    but requires changes to the network launcher itself.
  2. Document the issue in the troubleshooting guide so users can self-diagnose
    immediately — low effort, high impact, no code changes required.

Recommended Solution
Option 2 — documentation. It unblocks users today without touching any code.
The log file path and the port conflict error message are stable and reliable
signals, making them safe to document. Option 1 is worth a separate issue/PR
targeting the CLI itself.

Considerations

  • Security: None. No code changes, no new behavior.
  • Performance: None.
  • Users: Purely additive. Existing workflows are unaffected; new users get
    a faster path to resolution instead of hitting a dead end.
  • Breaking changes: None.
  • Maintenance: Low. The log file path and pocket-ic port binding behavior
    are unlikely to change frequently. If the default port ever changes, this
    section will need a one-line update.

Added troubleshooting section for 'icp network start' error.
@mitnick2012 mitnick2012 requested a review from a team as a code owner June 9, 2026 13:03
@cla-idx-bot

cla-idx-bot Bot commented Jun 9, 2026

Copy link
Copy Markdown

Dear @mitnick2012,

In order to potentially merge your code in this open-source repository and therefore proceed with your contribution, we need to have your approval on DFINITY's CLA.

If you decide to agree with it, please visit this issue and read the instructions there. Once you have signed it, re-trigger the workflow on this PR to see if your code can be merged.

— The DFINITY Foundation

@mitnick2012 mitnick2012 changed the title Document troubleshooting for network start issues Add ReadMe troubleshooting section for network start issues Jun 9, 2026
@marc0olo

marc0olo commented Jun 9, 2026

Copy link
Copy Markdown
Member

@mitnick2012 thanks for the contribution. I forwarded the issue to the team as I think it's better to fix the feedback in the icp-cli directly instead of documenting the problem across the board.

@mitnick2012

Copy link
Copy Markdown
Author

Yes its better to fix in the cli,and I suggest to let the fix of the problem here

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants