Skip to content

Respect TIKTOKEN_OFFLINE env var to prevent network access in offline mode#514

Open
Spectual wants to merge 1 commit intoopenai:mainfrom
Spectual:fix/respect-tiktoken-offline-env
Open

Respect TIKTOKEN_OFFLINE env var to prevent network access in offline mode#514
Spectual wants to merge 1 commit intoopenai:mainfrom
Spectual:fix/respect-tiktoken-offline-env

Conversation

@Spectual
Copy link
Copy Markdown

Problem

Fixes #513

In tiktoken 0.9.0+, the TIKTOKEN_OFFLINE environment variable is silently ignored. When the local cache is empty (e.g. fresh install in an air-gapped environment), read_file() proceeds to make HTTP requests even when TIKTOKEN_OFFLINE=1 is set, causing unexpected network errors instead of a clear actionable message.

The TIKTOKEN_CACHE_DIR variable was also not helping in this scenario because even when set correctly, if the cache file was absent the code would fall through to a network fetch.

Fix

  • In read_file(): check TIKTOKEN_OFFLINE before attempting any network fetch (http://, https://, or blobfile). If set, raise a ValueError with a clear message explaining the situation.
  • In read_file_cached(): guard the TIKTOKEN_CACHE_DIR="" (caching-disabled) path as well, raising early when TIKTOKEN_OFFLINE is set rather than delegating to read_file() after bypassing the cache lookup.

Local file paths ("://" not in blobpath) are unaffected and continue to work normally in offline mode.

Behaviour after fix

Scenario Before After
TIKTOKEN_OFFLINE=1, cache populated Worked Works (unchanged)
TIKTOKEN_OFFLINE=1, cache empty Silent network error Clear ValueError
TIKTOKEN_OFFLINE=1, TIKTOKEN_CACHE_DIR="" Silent network error Clear ValueError
No TIKTOKEN_OFFLINE, any path Worked Works (unchanged)

Test plan

  • Verify that setting TIKTOKEN_OFFLINE=1 with a pre-populated cache still loads the tokenizer successfully
  • Verify that setting TIKTOKEN_OFFLINE=1 with an empty cache raises ValueError with a clear message (no network attempt)
  • Verify that existing tests continue to pass

When TIKTOKEN_OFFLINE is set, network fetches should never be attempted.
Previously, read_file() would ignore this variable and attempt HTTP/blob
requests regardless, causing failures in air-gapped environments.

Fix read_file() to raise a clear ValueError when TIKTOKEN_OFFLINE is set
and the path requires a network fetch. Also guard the cache-disabled path
in read_file_cached() (TIKTOKEN_CACHE_DIR="") so that it too raises
instead of falling through to a network request.

Fixes openai#513
@debovis
Copy link
Copy Markdown

debovis commented Apr 17, 2026

While your effort is great, I would not say this "fixes" anything. You are just changing the error message.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] tiktoken 0.9.0 ignores TIKTOKEN_OFFLINE and TIKTOKEN_CACHE_DIR, still attempts network download

2 participants