[davidberenstein1957]

Description

Removes @suppress(Exception) from OfflineEmissionsTracker.__init__ in codecarbon/emissions_tracker.py, so configuration errors raised during construction propagate to the caller instead of being swallowed. Also wraps the body of BaseEmissionsTracker.__init__ (after _configure_multiple_runs) in try/except Exception, releasing self._lock if it was acquired before re-raising, so a constructor failure with allow_multiple_runs=False does not leave a stale lock blocking the next tracker. The offline-only region and country_2letter_iso_code type checks, which run before super().__init__, now raise TypeError with a descriptive message instead of a bare assert. In @track_emissions, tracker construction is now wrapped in its own try/except: on failure, the error is logged and the decorated function still runs untracked (the call to fn(*args, **kwargs) sits outside the except block, so the construction error is not chained via __context__/exc_info to any exception the function itself raises).

Related Issue

Fixes #1311

Motivation and Context

The decorator swallowed configuration errors raised during construction, most visibly the OSError from _set_from_conf when output_dir does not exist. The constructor then returned an object that had never reached _initialize_runtime_state() / _initialize_scheduler_state(), so it had no _start_time, _hardware, _scheduler, or _output_handlers. The subsequent start() and stop() calls are themselves suppressed, so they degraded into AttributeError warnings, and the run finished with no emissions file and no exception. Under the CLI default log_level="error", nothing was printed at all. The online EmissionsTracker already raises for the same input, so this also removes an asymmetry between the two constructors. Suppression on start, flush, and stop is deliberately left in place, since runtime measurement errors must never crash a user job; only construction, where the object invariants were never established, now fails loudly. This is a behavior change at a public boundary and is intended to ride a minor release (3.4.0), not a patch.

How Has This Been Tested?

Added test_offline_tracker_raises_on_invalid_output_dir in tests/test_offline_emissions_tracker.py, asserting both the offline and the online tracker raise OSError for a non-existent output_dir. It fails on master and passes with this change. test_offline_tracker_raises_on_invalid_region covers the offline-only region check (TypeError for a non-string region), and test_offline_tracker_raises_on_invalid_country_2letter_iso_code covers the same for country_2letter_iso_code; both new tests fail if @suppress(Exception) is restored on the constructor. test_offline_tracker_lowercases_valid_region and test_offline_tracker_uppercases_valid_country_2letter_iso_code guard against the stricter checks rejecting valid input. test_constructor_failure_releases_lock (in tests/test_emissions_tracker.py) asserts a constructor failure with allow_multiple_runs=False releases the lock file so a subsequent tracker can start. test_track_emissions_runs_function_when_tracker_construction_fails and test_untracked_function_errors_are_not_chained_to_construction_error cover the @track_emissions decorator: the function still runs untracked on a construction failure, and the construction error is not chained to an exception the function itself raises.

uv run pytest tests/test_offline_emissions_tracker.py tests/test_emissions_tracker.py -q
35 passed

Screenshots (if appropriate):

N/A

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

AI Usage Disclosure

• 🟥 AI-vibecoded
• 🟠 AI-generated
• ⭐ AI-assisted
• ♻️ No AI used

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the docs/how-to/contributing.md document.
• I have added tests to cover my changes.
• All new and existing tests passed.

CHANGELOG.md does not exist on master yet, so the release note lives in docs/reference/api.md under "Constructor errors (changed in v3.4.0)": OfflineEmissionsTracker no longer swallows exceptions raised while constructing the tracker; configuration errors (e.g. a non-existent output_dir) now propagate to the caller, matching EmissionsTracker. Suppression on start/flush/stop is unchanged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.85%. Comparing base (e159a68) to head (9f42c68).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1334      +/-   ##
==========================================
+ Coverage   93.66%   93.85%   +0.18%     
==========================================
  Files          50       50              
  Lines        5591     5610      +19     
==========================================
+ Hits         5237     5265      +28     
+ Misses        354      345       -9     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[benoit-cty]

🤖 This review comment was written and posted by Claude Opus 5.5 (AI assistant), at the request of @benoit-cty. Findings were checked by reading the code and running tests locally (merged with current master where relevant), but please double-check before acting on them.

Verdict: 💬 Needs a maintainer decision (leaning approve, for a minor release)

The bug is real. A bad output_dir returns a half-built OfflineEmissionsTracker that silently records nothing, and the new tests fail on master. Removing @suppress(Exception) from OfflineEmissionsTracker.__init__ (emissions_tracker.py:1312) matches the online EmissionsTracker, which already raises. start, stop and flush stay suppressed.

Behaviour change to be aware of:

• CodeCarbon's contract has been "never crash user code". With this PR:
  • @track_emissions(offline=True, output_dir="missing") builds the tracker inside wrapped_fn, so the decorated function never runs and the exception reaches the user's training job. Before, the job ran untracked.
  • with OfflineEmissionsTracker(...) now raises too.
• Suggestion for keeping both behaviours: keep direct construction strict (this PR), but in track_emissions catch construction errors, log them at ERROR, and run the wrapped function untracked.
• The docs note says "changed in v3.4.0" (latest tag is v3.3.1), so this must go into a minor release, not a patch. Please also add a changelog entry.

Nit:

• test_offline_tracker_raises_on_invalid_region expects an AssertionError from an assert (emissions_tracker.py ~L1344). Under python -O, asserts are stripped and nothing is raised. Please raise ValueError explicitly.

[davidberenstein1957]

Made the changes in e77657f: region / country_2letter_iso_code type checks now raise ValueError instead of assert.

Not done, pending a maintainer decision: whether track_emissions should catch construction errors and run the function untracked, and which release this lands in. No changelog file exists in the repo, so the entry is left for the release notes.

[davidberenstein1957]

Made the changes in 1e238ba: @track_emissions now logs construction errors and runs the function untracked, same as start_task. Direct construction still raises. Targeting a minor release (v3.4.0).

[benoit-cty]

Rebased on master (cfabf92 -> e159a68; the old merge commit was dropped). The head is now 9f42c68.

• Rebase: one conflict in BaseEmissionsTracker.__init__ (master added lines to the body that the PR had re-indented). Resolved by re-applying the try/except on master's body. No commit was redundant: master still has @suppress(Exception) on OfflineEmissionsTracker.__init__, the assert type checks, and no untracked fallback in @track_emissions.
• Re-indented __init__ (284782e): wrapping the whole __init__ body in try/except re-indented about 60 lines, and that is what conflicted. A small _release_lock_on_error decorator on __init__ now does the same job, so the __init__ diff is down to 1 line. test_constructor_failure_releases_lock still passes, and it fails when the decorator is removed.
• Docs (9f42c68): the v3.4.0 note in docs/reference/api.md now says that a non-string region/country_2letter_iso_code raises TypeError, and that @track_emissions logs the error and runs the function untracked.
• PR body: two small corrections. ValueError is now TypeError, to match the code and the tests. I removed "Master has since merged this change in", which was not true. One more thing in the body is now out of date: the Description still says the lock release wraps the __init__ body in try/except, but after 284782e it is a decorator.
• Coverage: all changed lines in codecarbon/ are covered by tests/test_offline_emissions_tracker.py and tests/test_emissions_tracker.py (100% of changed lines).
• Tests: these 2 files: 50 passed. Full suite (-m 'not integ_test'): the only failures are 4 RAPL permission tests, which also fail on master in this environment because it runs as root. pre-commit passes.

For the maintainer:

• Behaviour change in online mode: with @track_emissions, a failure while building the online tracker no longer raises. The function now runs untracked, as start_task already does. This follows the earlier review suggestion; please confirm it is wanted.
• Release: the change is labelled v3.4.0 (master is 3.3.2), so it needs a minor release.
• Possible follow-up: test_constructor_failure_releases_lock relies on the assert self._tracking_mode in [...] check, and asserts are skipped under python -O.

---

Generated by Claude Code