What causes "reload not configured" in sipeed/picoclaw?

Wire a reload callback (al.reloadFunc) when constructing the agent loop in your embedding

reload not configured

Error message

reload not configured

What it means

The ReloadConfig hook found al.reloadFunc == nil: no config-reload callback was attached to the agent loop when it was built, so /reload cannot do anything. The reload function is injected by the embedding process; its absence means this runtime instance was not given a way to re-read configuration.

Source

Thrown at pkg/agent/agent_command.go:288

			}
			if _, exists := al.channelManager.GetChannel(value); !exists && value != "cli" {
				return fmt.Errorf("channel '%s' not found or not enabled", value)
			}
			return nil
		},
	}
	rt.StopActiveTurn = func() (commands.StopResult, error) {
		if opts == nil {
			return commands.StopResult{}, fmt.Errorf("process options not available")
		}
		return al.stopActiveTurnForSession(opts.Dispatch.SessionKey)
	}
	if agent != nil && agent.ContextBuilder != nil {
		rt.ListSkillNames = agent.ContextBuilder.ListSkillNames
	}
	rt.ReloadConfig = func() error {
		if al.reloadFunc == nil {
			return fmt.Errorf("reload not configured")
		}
		return al.reloadFunc()
	}
	if agent != nil {
		if agent.ContextBuilder != nil {
			rt.ListSkillNames = agent.ContextBuilder.ListSkillNames
		}
		rt.GetModelInfo = func() (string, string) {
			return agent.Model, resolvedCandidateProvider(agent.Candidates, cfg.Agents.Defaults.Provider)
		}
		rt.SwitchModel = func(value string) (string, error) {
			value = strings.TrimSpace(value)
			modelCfg, err := resolvedModelConfig(cfg, value, agent.Workspace)
			if err != nil {
				return "", err
			}

			nextProvider, _, err := providers.CreateProviderFromConfig(modelCfg)

View on GitHub (pinned to 49183d7e8d)

Solutions

Wire a reload callback (al.reloadFunc) when constructing the agent loop in your embedding
Hide the /reload command in deployments that cannot reload
Restart the process as the manual alternative to reload

Defensive patterns

Strategy: type-guard

Validate before calling

if al.reloadFunc == nil { /* omit /reload from command help and dispatch */ }

Type guard

func reloadReady(al *AgentLoop) bool { return al.reloadFunc != nil }

Try / catch

err := rt.ReloadConfig()
if err != nil && strings.Contains(err.Error(), "reload not configured") {
    // unsupported in this embedding: fall back to process restart
}

Prevention

Always wire a reloadFunc when embedding and exposing /reload
Feature-detect: register the command only if the hook exists
Document restart-as-reload for minimal embeddings

When it happens

Trigger: Running /reload in an embedded AgentLoop whose constructor never set reloadFunc; tests instantiating the loop without wiring; a code path that deliberately omits reload support but leaves the command reachable.

Common situations: Custom binaries embedding pkg/agent without providing a reload callback; older embedding API that made reloadFunc optional; CI/one-shot invocations where reload is meaningless but the command leaked through.

Related errors

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