What causes "应用 [{client}] 推送地址无效：{_pushUrl}" in dromara/Sa-Token?

Set a complete absolute push-url, e.g. http://client.example.com/sso/push, or ensure server-url is absolute so the splice yields a valid URL

dromara/Sa-Token · error · SaSsoException

CODE_30023

CODE_30023

Error message

应用 [{client}] 推送地址无效：{_pushUrl}

What it means

Thrown by SaSsoClientModel.splicingPushUrl when the merged push URL (serverUrl joined with pushUrl via SaFoxUtil.spliceTwoUrl) fails SaFoxUtil.isUrl (code 30023). SSO message push (logout/notification callbacks) needs a valid absolute URL; if the result is blank or malformed the model refuses to return it.

Source

Thrown at sa-token-plugin/sa-token-sso/src/main/java/cn/dev33/satoken/sso/config/SaSsoClientModel.java:93

    /**
     * 以数组形式写入允许的授权回调地址
     * @param url 所有集合
     * @return 对象自身
     */
    public SaSsoClientModel setAllow(String ...url) {
        this.setAllowUrl(SaFoxUtil.arrayJoin(url));
        return this;
    }

    /**
     * 获取拼接 url：此 Client 端推送消息的地址
     *
     * @return /
     */
    public String splicingPushUrl() {
        String _pushUrl = SaFoxUtil.spliceTwoUrl(getServerUrl(), getPushUrl());
        if ( ! SaFoxUtil.isUrl(_pushUrl)) {
            throw new SaSsoException("应用 [" + getClient() + "] 推送地址无效：" + _pushUrl).setCode(SaSsoErrorCode.CODE_30023);
        }
        return _pushUrl;
    }


    // get set

    /**
     * @return Client 名称标识
     */
    public String getClient() {
        return client;
    }

    /**
     * @param client Client 名称标识
     */
    public SaSsoClientModel setClient(String client) {

View on GitHub (pinned to ac2c7f6e94)

Solutions

Set a complete absolute push-url, e.g. http://client.example.com/sso/push, or ensure server-url is absolute so the splice yields a valid URL
Verify both fields after builder migration: new SaSsoClientModel().setServerUrl("http://client.example.com").setPushUrl("/sso/push")
If push is not needed, avoid code paths that call splicingPushUrl or disable message push in SSO config

Example fix

// before
new SaSsoClientModel().setClient("client1").setPushUrl("/sso/push"); // no server-url
// after
new SaSsoClientModel().setClient("client1").setServerUrl("http://client.example.com").setPushUrl("/sso/push");

Defensive patterns

Strategy: validation

Validate before calling

String merged = SaFoxUtil.spliceTwoUrl(clientModel.getServerUrl(), clientModel.getPushUrl());
if (!SaFoxUtil.isUrl(merged)) throw new IllegalStateException("push url invalid, configure absolute server-url + push-url: " + merged);

Try / catch

try { clientModel.splicingPushUrl(); } catch (SaSsoException e) { if (e.getCode() == 30023) { log.error("SSO push url misconfigured for client {}", clientModel.getClient()); disablePushUntilFixed(); return; } throw e; }

Prevention

Validate every SaSsoClientModel with an isUrl check at config load time
Always configure server-url as an absolute URL with scheme, even when push-url is relative

When it happens

Trigger: Configuring a SaSsoClientModel whose pushUrl is empty/null while serverUrl is also missing or relative, or whose combined value is not a parseable absolute URL; then triggering a push (splicingPushUrl call) during SSO logout/message push.

Common situations: server-url not set in test environment; push-url given as a relative path '/sso/push' with no resolvable server-url; trailing configuration migration to the new SaSsoClientModel builder where the push url field was dropped; reverse proxy setups where the configured base URL lacks scheme.

Related errors

AI-assisted analysis of dromara/Sa-Token@ac2c7f6e94 (2026-08-14). Data as JSON: /api/errors/1bf6206e7e4f47bd. Report an issue: GitHub.