Can't run space with the jupyterlab template?

Spaces
1

Creating a space with the jupyterlab docker template but it keeps being an empty page despite status turned `Running`. The container log shows failure of:

[I 2025-12-21 05:44:40.012 ServerApp] jupyter_server_terminals | extension was successfully loaded.
[I 2025-12-21 05:44:40.013 LabApp] JupyterLab extension loaded from /home/user/miniconda/lib/python3.9/site-packages/jupyterlab
[I 2025-12-21 05:44:40.013 LabApp] JupyterLab application directory is /home/user/miniconda/share/jupyter/lab
[I 2025-12-21 05:44:40.014 LabApp] Extension Manager is 'pypi'.
[W 2025-12-21 05:44:40.014 LabApp] Failed to instantiate the extension manager pypi. Falling back to read-only manager.
    Traceback (most recent call last):
      File "/home/user/miniconda/lib/python3.9/site-packages/jupyterlab/labapp.py", line 837, in initialize_handlers
        ext_manager = manager_factory(app_options, listings_config, self)
      File "/home/user/miniconda/lib/python3.9/site-packages/jupyterlab/extensions/__init__.py", line 46, in get_pypi_manager
        return PyPIExtensionManager(app_options, ext_options, parent)
      File "/home/user/miniconda/lib/python3.9/site-packages/jupyterlab/extensions/pypi.py", line 134, in __init__
        self._httpx_client = httpx.AsyncClient(proxies=proxies)
    TypeError: __init__() got an unexpected keyword argument 'proxies'`
1 Like
2

Seems httpx related issue?

What your log error actually means

Your traceback is a dependency mismatch between JupyterLab’s PyPI Extension Manager and httpx:

  • JupyterLab is trying to create an httpx.AsyncClient(proxies=...).
  • httpx 0.28.0 removed the proxies argument.
  • So JupyterLab crashes that specific component with TypeError: __init__() got an unexpected keyword argument 'proxies'. (GitHub)

Important nuance: in your log, JupyterLab says it is “falling back to read-only manager.” That means the extension manager fails, but JupyterLab itself may still be running. So the blank page on a Hugging Face Space is often not caused solely by this warning.

This exact JupyterLab error is tracked upstream. (GitHub)

Why this happens (root cause)

1) httpx API change (the direct cause of the TypeError)

httpx 0.28.0 removed proxies. This is documented in their release notes. (GitHub)

So if your environment has:

  • JupyterLab version that still calls AsyncClient(proxies=...), and
  • httpx >= 0.28.0,

you get exactly the exception you pasted. (GitHub)

2) “Who pulled in httpx 0.28+?”

On Spaces, this commonly happens because some other dependency upgrades httpx (directly or indirectly). This same breakage showed up across the ecosystem (OpenAI Python SDK, LangChain, etc.) when httpx 0.28.0 landed. (GitHub)

3) JupyterLab’s own moving target around httpx

JupyterLab added fixes and also had a period of tight pinning around httpx 0.28.x because the API surface changed quickly. (GitHub)

Fix the proxies crash (pick one approach)

Option A (usually best): upgrade JupyterLab to a version that handles newer httpx

JupyterLab 4.2.7 notes fixes specifically around extension manager + httpx versions (including proxy handling). (jupyterlab.readthedocs.io)

Practical pin set (example):

jupyterlab>=4.2.7,<5
httpx>=0.28.0,<0.29

This path is best if other libs in your Space already require httpx 0.28+.

Option B (quick workaround): pin httpx below 0.28

If you do not care about staying on httpx 0.28+ (and no other dependency demands it), pin:

httpx<0.28

This is exactly the “temporary override” people used in other projects when they hit the same break. (GitHub)

Option C (often best for hosted Spaces): disable the PyPI extension manager entirely

On Hugging Face Spaces, you often do not want “install random packages from the UI” anyway.

JupyterLab supports switching extension manager to read-only:

jupyter lab --LabApp.extension-manager=readonly

This avoids the whole PyPI manager path. (jupyterlab.readthedocs.io)

Why the Space shows an empty page even though it says “Running”

On Hugging Face Spaces, a “blank app frame” usually comes from hosting/proxy/browser constraints, not from the extension manager warning.

Cause 1: Cookie + iframe restrictions (very common)

Hugging Face serves your app on *.hf.space inside an iframe on a huggingface.co page. Browsers restrict cookies in this setup. Hugging Face documents this explicitly. (Hugging Face)

JupyterLab uses cookies for auth/session (even when token-based). If cookies are blocked or have the wrong SameSite policy, you can get a blank screen, failed redirects, or a login loop that looks like “empty page”.

Concrete mitigation used by a known-working JupyterLab Space:

  • set cookie SameSite=None; Secure=True
  • allow iframe embedding via CSP frame-ancestors *
  • often also disable XSRF checks in this proxied embedding scenario

Example launch flags from an existing JupyterLab Space template: (Hugging Face)

  • --ServerApp.tornado_settings="{'headers': {'Content-Security-Policy': 'frame-ancestors *'}}"
  • --ServerApp.cookie_options="{'SameSite': 'None', 'Secure': True}"
  • --ServerApp.disable_check_xsrf=True

If your JupyterLab docker template does not set these, add them.

Also note: private Spaces have had multiple “Running but blank” reports in the community. (Hugging Face Forums)

Cause 2: Wrong port exposed (also common)

Docker Spaces expect your web server on port 7860 by default (or whatever you set via app_port). If Jupyter starts on 8888, Spaces can show “Running” while the embedded page is effectively empty. (Hugging Face)

So ensure:

  • JupyterLab is launched with --port 7860 --ip 0.0.0.0
  • README YAML includes app_port: 7860 if you rely on defaults (or set it explicitly)

Hugging Face’s Docker Spaces docs call this out. (Hugging Face)

Cause 3: Private Space visibility and authentication edge cases

Private resources can present as 404 to anyone without proper auth context. People have reported “public works, private blank/404”. (Hugging Face Forums)

Even if you are logged in, aggressive tracking protection can block the iframe’s cookie context and break “private embed auth”.

Minimal “known-good” checklist for a JupyterLab Space

  1. Port
  1. Iframe + cookies
  • CSP frame-ancestors *
  • cookies SameSite=None, Secure=True (Hugging Face)
  1. Token
  • Set JUPYTER_TOKEN (HF docs note default is huggingface and recommend setting one). (Hugging Face)
  1. Dependency sanity
  • Either (A) upgrade JupyterLab to match httpx 0.28+ behavior or (B) pin httpx < 0.28. (GitHub)
  1. Avoid UI extension installs

Similar cases online (the ones that match your symptoms)

Same proxies TypeError pattern

  • JupyterLab issue: “Failed to instantiate the extension manager pypi” with the same AsyncClient(proxies=...) crash. (GitHub)
  • httpx release notes: proxies removed in 0.28.0. (GitHub)
  • OpenAI Python SDK issue: same TypeError after upgrading httpx 0.28.0. (GitHub)
  • LangChain issue: same TypeError, workaround is pinning httpx <0.28.0. (GitHub)

“Running but blank” on Hugging Face (private/public differences, iframe issues)

  • HF forums: reports of Private Spaces not loading apps even while “Running”. (Hugging Face Forums)
  • Gradio issue: “private space not show … solved by making it public” class of symptom. (GitHub)
  • HF docs: explicit explanation of cookie limitations due to iframe + cross-domain hosting. (Hugging Face)

If you want a fast diagnosis path (no guessing)

  1. Confirm versions in your Space build logs:
python -c "import jupyterlab, httpx; print('jupyterlab', jupyterlab.__version__, 'httpx', httpx.__version__)"
  1. Confirm Jupyter is actually listening on 7860:
python -c "import socket; s=socket.socket(); print(s.connect_ex(('127.0.0.1',7860))==0)"
  1. Open browser devtools on the Space page:
  • If you see cookie warnings or blocked storage, this is the iframe cookie limitation case. (Hugging Face)
  • If network shows nothing on the app iframe, suspect wrong port. (Hugging Face)

Summary

  • Your proxies TypeError is a JupyterLab ↔ httpx mismatch caused by httpx 0.28.0 removing proxies. (GitHub)
  • Fix it by either upgrading JupyterLab, pinning httpx < 0.28, or forcing extension manager read-only. (jupyterlab.readthedocs.io)
  • The blank Space page is often cookie/iframe or wrong port, not the extension manager warning. (Hugging Face)
  • Known-good Space launch flags include SameSite=None; Secure cookies and frame-ancestors *. (Hugging Face)