Skip to content

Fix AttributeError when port is already in use#8675

Open
dcabib wants to merge 1 commit intoaws:developfrom
dcabib:fix/port-already-in-use-error-7244
Open

Fix AttributeError when port is already in use#8675
dcabib wants to merge 1 commit intoaws:developfrom
dcabib:fix/port-already-in-use-error-7244

Conversation

@dcabib
Copy link
Contributor

@dcabib dcabib commented Feb 20, 2026

Issue

Fixes #7244

Problem

When SAM CLI attempts to bind to a port that's already in use, users see a cryptic AttributeError: 'str' object has no attribute 'decode' instead of a helpful error message about which port is occupied.

This occurs because:

  1. In docker-py >= 7.0, APIError.explanation is a str (not bytes)
  2. The code calls .decode() on it, causing AttributeError
  3. Case-sensitive check ("Ports") misses lowercase variations ("ports")

Solution

  • Added safe_decode_docker_message() function that handles both bytes (docker-py < 7.0) and str (docker-py >= 7.0)
  • Updated error detection to use case-insensitive check (.lower())
  • Added 8 comprehensive unit tests covering all scenarios

Testing

  • ✅ All 6931 existing tests pass
  • ✅ Added 8 new tests (100% passing)
  • ✅ Coverage maintained at 94.04%
  • ✅ Lint and formatting checks pass
  • ✅ Tested with samdev local invoke on occupied port

Result

Users now see the actual port error message:

Error: ports are not available: exposing port TCP 127.0.0.1:5005 -> 127.0.0.1:0: listen tcp4 127.0.0.1:5005: bind: address already in use

Instead of:

AttributeError: 'str' object has no attribute 'decode'

Checklist

  • Code builds correctly
  • New/updated tests pass
  • All tests pass (make test)
  • Coverage maintained at 94%+
  • Lint checks pass (make lint)
  • Formatting is correct (make black-check)
  • Issue linked in commit and PR description
  • Added comprehensive unit tests
  • Backwards compatible (no breaking changes)

This commit fixes two related issues when Docker port binding fails:

1. AttributeError on ex.explanation.decode() - In docker-py >= 7.0,
   the explanation property is already a str, not bytes. Calling
   .decode() on a string raises AttributeError, completely masking
   the actual "port already in use" error.

2. Case sensitivity in error detection - The code checked for
   "Ports are not available" (capital P) but Docker may return
   "ports are not available" (lowercase p), causing the condition
   to fail and miss the specific error handling.

Changes:
- Added safe_decode_docker_message() function in utils.py that handles
  both bytes (docker-py < 7.0) and str (docker-py >= 7.0)
- Updated container.py to use case-insensitive check (.lower())
- Added comprehensive unit tests covering both scenarios

This ensures users see the helpful port error message instead of a
cryptic AttributeError, regardless of their docker-py version.

Fixes aws#7244

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@dcabib dcabib requested a review from a team as a code owner February 20, 2026 15:56
@github-actions github-actions bot added area/local/start-api sam local start-api command area/local/invoke sam local invoke command area/local/start-invoke pr/external stage/needs-triage Automatically applied to new issues and PRs, indicating they haven't been looked at. labels Feb 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/local/invoke sam local invoke command area/local/start-api sam local start-api command area/local/start-invoke pr/external stage/needs-triage Automatically applied to new issues and PRs, indicating they haven't been looked at.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

'str' object has no attribute 'decode' when PortAlreadyInUse error is raised.

1 participant