What causes "api base is required" in sipeed/picoclaw?

Pass a real base: picoclaw model add -b https://api.openai.com/v1 -k

api base is required

Error message

api base is required

What it means

fetchOpenAIModels refuses to build a request when the api base is empty or only whitespace. In the CLI, --api-base (-b) is a required flag, so cobra already rejects a missing flag; this error is reached when the flag is present but blank (-b '' or -b ' ', trimmed to empty by runAdd) or when the add flow is invoked programmatically with no base while -m/--model is omitted (a model id skips the fetch entirely).

Source

Thrown at cmd/picoclaw/internal/model/online.go:26

	"strings"
	"time"
)

type modelEntry struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
}

type modelsAPIResponse struct {
	Data []modelEntry `json:"data"`
}

// fetchOpenAIModels GETs <baseURL>/models with Bearer auth and accepts both the
// {data:[…]} envelope and a bare array shape used by various OpenAI-compatible servers.
func fetchOpenAIModels(baseURL, apiKey string) ([]modelEntry, error) {
	if strings.TrimSpace(baseURL) == "" {
		return nil, fmt.Errorf("api base is required")
	}
	if strings.TrimSpace(apiKey) == "" {
		return nil, fmt.Errorf("api key is required")
	}

	url := strings.TrimRight(baseURL, "/") + "/models"

	client := &http.Client{Timeout: 15 * time.Second}
	req, err := http.NewRequest(http.MethodGet, url, nil)
	if err != nil {
		return nil, fmt.Errorf("build request: %w", err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)

	resp, err := client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("request failed: %w", err)
	}

View on GitHub (pinned to 49183d7e8d)

Solutions

Pass a real base: picoclaw model add -b https://api.openai.com/v1 -k <key>
Include the scheme (https:// or http://) and the documented prefix (often /v1)
If a script builds -b from a variable, assert the variable is non-empty before invoking picoclaw

Example fix

# before (OPENAI_BASE unset in this shell)
$ picoclaw model add -b "$OPENAI_BASE" -k sk-...
fetch models: api base is required

# after
$ OPENAI_BASE=https://api.openai.com/v1
$ picoclaw model add -b "$OPENAI_BASE" -k sk-...

Defensive patterns

Strategy: validation

Validate before calling

if strings.TrimSpace(apiBase) == "" {
  return fmt.Errorf("--api-base is empty; pass a full URL like https://api.openai.com/v1")
}
if _, err := url.ParseRequestURI(strings.TrimSpace(apiBase)); err != nil {
  return fmt.Errorf("--api-base %q is not a valid URL", apiBase)
}

Type guard

func isAPIBaseRequiredError(err error) bool {
  return err != nil && strings.Contains(err.Error(), "api base is required")
}

Try / catch

if err := fetchOpenAIModels(apiBase, apiKey); err != nil {
  if isAPIBaseRequiredError(err) {
    // abort before network use; prompt for a non-empty base
  }
  return err
}

Prevention

Assert ${VAR:+x} style checks before injecting variables into -b
Include scheme and host in every --api-base value
Prefer -m <model-id> when the base is uncertain — the fetch is skipped entirely

When it happens

Trigger: picoclaw model add -b "" -k <key> with no -m; scripts injecting an unset/empty environment variable into -b; programmatic calls of runAdd with empty apiBase and empty modelID.

Common situations: Automation wrapping the command with a variable that is unset in that shell; users blanking the flag expecting a prompt; copy-paste from examples where the base placeholder was never replaced.

Related errors

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/44d6f4875a5e0759. Report an issue: GitHub.