Troubleshooting

ImportError: jevimage.load runs the encoder in this process, which needs torch and
transformers: pip install 'jevimage[local]'
To use a server instead - no torch required - call jevimage.connect(url).
(underlying import error: No module named 'torch')

pip install 'jevimage[local]'          # run the encoder here

import jevimage
jev = jevimage.connect("http://your-host:8000")   # someone else runs it

import jevimage
jevimage.available()
jevimage.connect("http://127.0.0.1:8123").health()

['clip-vit-l-14', 'dfn5b-h-14-384', 'metaclip2-huge', 'siglip2-base-224',
 'siglip2-base-384', 'siglip2-giant-384', 'siglip2-so400m-384']
{'encoder': 'toy', 'dim': 16, 'device': 'cpu',
 'primitives': ['choice', 'score', 'noul', 'head'], 'heads': 0,
 'auth': 'open', 'version': '0.1.0'}

$ jev ask photo.png --choice red="a red square" blue="a blue square"
jev: this command runs the encoder locally, which needs torch:
       pip install 'jevimage[local]'
     or point it at a server that already has one:
       jev ask --url http://host:8000   (also $JEV_URL)
exit 1

jev ask photo.png --url http://127.0.0.1:8123 --choice red="a red square" blue="a blue square"
export JEV_URL=http://127.0.0.1:8123 JEV_API_KEY=s3cret   # same thing, once

$ jev heads --url http://127.0.0.1:8123
no heads in http://127.0.0.1:8123. Train one: jev train NAME FOLDER

$ jev serve
jev: jev serve needs uvicorn: pip install 'jevimage[serve]'
exit 1

jevimage.load("siglip-base")

KeyError: "unknown encoder 'siglip-base'. Available: clip-vit-l-14, dfn5b-h-14-384,
metaclip2-huge, siglip2-base-224, siglip2-base-384, siglip2-giant-384,
siglip2-so400m-384. Register your own with jevimage.register(name, factory) - from
Python, in the process that will serve it; the `jev` command only sees these built-in
names, because it never imports your code."

import jevimage, uvicorn
from jevimage.server import build_app

jev = jevimage.load(MyEncoder())          # or jevimage.load("mine") after register()
uvicorn.run(build_app(jev), host="127.0.0.1", port=8000)

from jevimage import encoders

for bad in ("a++b", "+a", "a+", "a+ +b", "+"):
    try:
        encoders.load(bad)
    except ValueError as e:
        print(f"ValueError: {e}")

ValueError: malformed ensemble name 'a++b': join two or more encoder names with single
'+', e.g. siglip2-base-224+dfn5b-h-14-384
ValueError: malformed ensemble name '+a': join two or more encoder names with single
'+', e.g. siglip2-base-224+dfn5b-h-14-384
ValueError: malformed ensemble name 'a+': join two or more encoder names with single
'+', e.g. siglip2-base-224+dfn5b-h-14-384
ValueError: malformed ensemble name 'a+ +b': join two or more encoder names with single
'+', e.g. siglip2-base-224+dfn5b-h-14-384
ValueError: malformed ensemble name '+': join two or more encoder names with single
'+', e.g. siglip2-base-224+dfn5b-h-14-384

class Half:
    name, dim = "half", 8
jevimage.load(Half()).ask("photo.png", {"q": {"type": "choice", "criteria": {"a": "x", "b": "y"}}})

AttributeError: 'Half' object has no attribute 'img'

NotImplementedError:

name              # str, recorded in every head you train under it
dim               # int, embedding width
img(list[PIL])    # -> (n, dim) fp32, L2-normalised
txt(list[str])    # -> (n, dim) fp32, L2-normalised

class RawEnc(Toy):
    name = "rawenc"
    def img(self, ims): return torch.ones(len(ims), self.dim) * 3

jevimage.load(RawEnc()).ask("photo.png", {"scene": {"type": "choice", "criteria": {"a": "x", "b": "y"}}})

ValueError: embeddings must be L2-normalised, got norm 12; wrap your encoder's output
in jevimage.encoders.unit()

from jevimage.encoders import unit

def img(self, images):
    return unit(self.model.get_image_features(**self.proc(images=images, return_tensors="pt")))

import time, jevimage
t = time.time(); jev = jevimage.load("siglip2-base-224"); print(f"{time.time()-t:.1f}s")

9.7s      # 16-thread laptop CPU (i7-12650H), weights already in ~/.cache/huggingface
24.7s     # the same call, same box, under heavy load

# the pair form - works on EVERY encoder, better calibrated, prefer it
{"type": "noul", "criteria": {"true": "the lights are on", "false": "the lights are off"}}

# the single-caption form - needs an encoder with BOTH logit_scale and logit_bias
{"type": "noul", "instructions": "the lights are on"}

jev.ask("photo.png", {"q": {"type": "noul", "instructions": "it is dark"}})

ValueError: encoder 'toy' has no calibrated sigmoid, so a single-caption noul cannot
produce a probability. Give a {"true": ..., "false": ...} criteria pair instead, which
works on every encoder.

jev = jevimage.load("siglip2-base-224")
jev.encoder.logit_scale, jev.encoder.logit_bias, jev.encoder.dim
jev.ask("ds/red/0.png", {"q": {"type": "noul", "instructions": "a red square"}})

logit_scale 112.0 logit_bias -16.75 dim 768
{'q': <noul 0.169>}

e = jevimage.encoders.load("toycal+toycal2")     # two toys, calibrated 100.0 and 120.0
print(f"ensemble: {e.name} dim {e.dim} logit_scale {e.logit_scale} logit_bias {e.logit_bias}")
jevimage.load(e).ask(img, {"q": {"type": "noul", "instructions": "a red square"}})

ensemble: toycal+toycal2 dim 32 logit_scale 110.0 logit_bias None
ValueError: encoder 'toycal+toycal2' has no calibrated sigmoid, so a single-caption noul
cannot produce a probability. Give a {"true": ..., "false": ...} criteria pair instead,
which works on every encoder.

ensemble: toy+toy2 dim 32 logit_scale None logit_bias None

{"type": "noul", "criteria": {"true": "it is dark", "false": "it is brightly lit"}}

{"type": "noul", "criteria": {"true": "outdoors", "false": ""}}

ValueError: noul criteria has an empty 'false' caption; both sides of a pair need text

jev.ask(img, questions, temperature=0)
jev.ask(img, questions, temperature=-1)
jev.ask(img, questions, temperature=float("inf"))
jev.ask(img, questions, temperature="0.1")
jev.ask(img, questions, temperature=True)

ValueError: temperature must be greater than 0, got 0
ValueError: temperature must be greater than 0, got -1
ValueError: temperature must be finite, got inf; an infinite temperature makes every option equally likely
ValueError: temperature must be a number greater than 0, got '0.1'
ValueError: temperature must be a number greater than 0, got True

jev.ask(img, {"q": {"type": "head", "head": "nope"}})

ValueError: unknown head 'nope'; trained heads: colours

other = jevimage.load(ToyCalibrated(), heads_dir="heads")   # a different encoder
other.ask(img, {"q": {"type": "head", "head": "colours"}})

ValueError: head 'colours' was trained on encoder 'toy' but this instance runs
'toy-calibrated'. Load 'toy', or retrain the head here.

ValueError: head 'colours' was trained on encoder 'toy' but this instance runs
'toy-calibrated'. Load 'toy', or retrain the head here.

jev = jevimage.load(Toy())                  # the encoder the head names
head = jev.train("colours", "ds/")          # or refit under the new one

ValueError: head 'nopro' records no encoder, so it cannot be checked against this one;
retrain it

ValueError: head 'damaged' lists 3 classes but its weights have 2 columns; the file is
damaged, retrain it

ValueError: invalid head name '../evil': use 1-64 characters from [A-Za-z0-9._-],
starting with a letter or digit

jev = jevimage.load(Toy(), heads_dir="heads")     # heads/junk.pt is not a torch file
sorted(jev.heads)
jev.heads.broken

['colours']
{'junk': 'UnpicklingError: Weights only load failed. In PyTorch 2.6, we changed the
default value of the `weights_only` argument in `torch.load` from `False` to `True`.
Re-running `torch.'}

$ jev heads
junk.pt is present but unreadable: UnpicklingError: Weights only load failed. ...
head     encoder  classes   n  held out     created
colours      toy        2  12     50.0%  2026-09-23

jev.heads["junk"]
jev.ask(img, {"q": {"type": "head", "head": "junk"}})

KeyError: 'junk.pt is present in heads but unreadable: UnpicklingError: Weights only
load failed. In PyTorch 2.6, we changed the default value of the `weights_only`
argument in `torch.load` from `False` to `True`. Re-running `torch.. Delete it, or
retrain the head.'

ValueError: unknown head 'nope'; trained heads: colours

{"detail":"head 'noemb' was saved without its embeddings, so it cannot be compared;
retrain it to restore this"}   [HTTP 409]

Training did not beat the prompts here - try more examples per class, or a bigger encoder.

seen = []
class Watch(Toy):
    name = "watch"
    def img(self, ims):
        seen.append(len(ims)); return super().img(ims)

j = jevimage.load(Watch(), heads_dir="heads")
j.train("w", "ds")                        # 12 images
j.train("w2", "ds", max_per_class=2)

img() batch sizes, train on 12 images: [12]
img() batch sizes, max_per_class=2: [4]

jev.train("street", "ds/", max_per_class=200)          # cap the images

# embed in chunks yourself, then fit on the embeddings
import torch, jevimage
from jevimage import as_examples
from jevimage import training                            # module, not in __all__

images, labels = as_examples("ds/")
embs = torch.cat([jev.embed(images[i:i + 32]) for i in range(0, len(images), 32)])
head = training.train(embs, labels)
head["encoder"] = jev.encoder.name
jev.heads.save("street", head)
print(jev.head("street"))
print(jev.ask("ds/red/0.png", {"q": {"type": "head", "head": "street"}}))

<Head 'street' 2 classes, 12 examples, 50.0% held out>
{'q': <head 'red' p=0.986>}

jev.ask_embedding(torch.full((1, 16), float("nan")), {"scene": {"type": "choice", "criteria": {"a": "x", "b": "y"}}})

ValueError: scene.probabilities.a is nan: the image could not be scored (its
embedding is not finite)

ValueError: busy.score is nan: the image could not be scored (its embedding is not finite)
ValueError: h.probabilities.blue is nan: the image could not be scored (its embedding is not finite)

class NanEnc(Toy):
    name = "nanenc"
    def img(self, ims): return torch.full((len(ims), self.dim), float("nan"))

jevimage.load(NanEnc()).ask("photo.png", {"scene": {"type": "choice", "criteria": {"a": "x", "b": "y"}}})

ValueError: scene.probabilities.a is nan: the image could not be scored (its
embedding is not finite)

FileNotFoundError: no such image file: 'nope.png'. Pass a path that exists, raw image
bytes, a PIL.Image, or a 'data:image/...;base64,...' string.

TypeError: cannot read an image from int; pass a path, bytes, a PIL.Image, or a data URL

jev.ask([img, img], questions)

TypeError: ask() takes one image, got a list of 2. Loop over them, or call embed() once
and ask_embedding() per row.

embs = jev.embed([img, img])                   # one batched pass; embed() takes a list
[jev.ask_embedding(e, questions)["q"] for e in embs]

[<choice 'a' p=0.978>, <choice 'a' p=0.978>]

from jevimage import JevError

try:
    jev.ask(img, questions)
except JevError as e:
    print(e.status, e.detail)

ValueError: url '127.0.0.1:8123' has no scheme; use 'http://127.0.0.1:8123'

JevError: cannot reach jev at http://127.0.0.1:9 ([Errno 111] Connection refused).
Start one with `jev serve`, or pass the URL it is actually listening on.

JevError: cannot reach jev at http://no-such-host.invalid:8000 ([Errno -2] Name or
service not known). Start one with `jev serve`, or pass the URL it is actually
listening on.

JevError: GET http://127.0.0.1:42513/v1/health did not answer within 2s; raise timeout=
if the server is loading a model

jev = jevimage.connect(url, timeout=300)

jev train street dataset/ --url http://127.0.0.1:8123 --timeout 600
export JEV_TIMEOUT=600          # same thing, once

JevError: send 'Authorization: Bearer <key>' with a key this server was started with
(JEV_API_KEYS) [HTTP 401 from GET http://127.0.0.1:8124/v1/heads]

jevimage.connect(url, api_key="s3cret")

export JEV_API_KEY=s3cret      # what the CLI reads, alongside $JEV_URL

at most 8 images per request; got 9
images[0] is 13MB of base64; the limit is 12MB per image
images[0] is 8000x8000; the limit is 50MP per image
images[0] is too large to decode: Image size (196000000 pixels) exceeds limit of
178956970 pixels, could be decompression bomb DOS attack.

len(jev.embed(["ds/red/0.png"] * 20))

20

at most 4000 examples per request; got 4001

images[0] is GIF; this server reads JPEG, PNG, WEBP

images[0] is not a base64-encoded image; send the raw bytes base64'd, or a
'data:image/png;base64,...' URL
images[0] is a truncated or corrupt PNG
send 'image' (one base64 string) or 'images' (a list)
send 'image' or 'images', not both: 'image' returns one answer object, 'images' returns
a list

examples[1] is not a base64-encoded image; send the raw bytes base64'd, or a
'data:image/png;base64,...' URL

JevError: unknown head 'nope'; trained heads: colours, docref_colours2
[HTTP 422 from POST http://127.0.0.1:8123/v1/ask]

{"detail": [{"type": "missing", "loc": ["body", "questions"], "msg": "Field required",
"input": {"image": "x"}}]}
{"detail": [{"type": "less_than_equal", "loc": ["body", "epochs"], "msg": "Input should
be less than or equal to 5000", "input": 99999, "ctx": {"le": 5000}}]}

JevError: no head named 'nope' (have: colours, docref_colours2)
[HTTP 404 from GET http://127.0.0.1:8231/v1/heads/nope]

JevError: junk.pt is present but unreadable: UnpicklingError: Weights only load failed.
... Delete it, or retrain the head. [HTTP 404 from POST http://127.0.0.1:8231/v1/ask]

$ jev rm nope --url http://127.0.0.1:8123
jev: no head named 'nope' on http://127.0.0.1:8123
exit 1

a = jev.ask(img, {"scene": {"type": "choice", "criteria": {"a": "x", "b": "y"}}})["scene"]
a.noul

AttributeError: 'choice' answers have no 'noul'; this one has: type, choice,
probabilities, confidence

<choice 'a' p=0.978>

json.dumps(a)

{"type": "choice", "choice": "a", "probabilities": {"a": 0.977548, "b": 0.022453},
 "confidence": 0.955095}