larksuite/cli · error

remote meta: unexpected msg %q

Error message

remote meta: unexpected msg %q

What it means

fetchRemoteMerged fetches the remote metadata registry wrapped in an envelope response. When the envelope decodes but its Msg field is not "succeeded", the fetch fails with this error. It indicates the remote metadata service reported a non-success status rather than returning registry data.

Source

Thrown at internal/registry/remote.go:212

	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		return nil, nil, &httpError{StatusCode: resp.StatusCode}
	}

	body, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseSize))
	if err != nil {
		return nil, nil, err
	}

	// Parse the envelope response
	var envelope remoteResponse
	if err := json.Unmarshal(body, &envelope); err != nil {
		return nil, nil, err
	}
	if envelope.Msg != "succeeded" {
		return nil, nil, fmt.Errorf("remote meta: unexpected msg %q", envelope.Msg)
	}

	var parsed MergedRegistry
	if len(envelope.Data) > 0 {
		if err := json.Unmarshal(envelope.Data, &parsed); err != nil {
			return nil, nil, fmt.Errorf("remote meta: parse data: %w", err)
		}
	}

	// If data.services is nil, the version is up-to-date (not modified)
	if parsed.Services == nil {
		return nil, nil, nil
	}

	// Cache the data portion verbatim (see remoteResponse for why not a typed
	// re-marshal).
	return envelope.Data, &parsed, nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Inspect the quoted msg in the error to see what the remote service returned, then address that upstream status.
2. Retry later or trigger a manual refresh — transient service issues usually clear up.
3. Verify the metadata endpoint URL / network path (proxy, VPN, custom endpoint config) points at the real metadata service.
4. Fall back to the cached or bundled registry metadata (internal/registry/meta_data.json) if available.

merged, _, err := fetchRemoteMerged(ctx, client)
if err != nil {
	if strings.HasPrefix(err.Error(), "remote meta: unexpected msg") {
		// log the msg, back off and retry, then fall back to cached meta
		return loadCachedRegistry()
	}
	return err
}

When it happens

Trigger: Any remote meta sync path (doSyncFetch, doBackgroundRefresh, TestFetchRemoteMerged_*) where the HTTP body is a valid envelope whose msg is not "succeeded" — e.g. the endpoint returned an error/status message.

Common situations: Remote metadata service degraded or rejecting the request inside a 200 envelope; API gateway/proxy altering the response; pointing the CLI at a non-production endpoint that answers with a different msg value.

Related errors

• remote meta: parse data: %w
• annotated_csv did not parse into the rows the server reporte
• lark-cli timed out after {timeout}s
• {json.dumps(envelope, ensure_ascii=False)}
• L1: inputSchema must not be nil

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/aa3c956cb392835d. Report an issue: GitHub.