framework7io/framework7 · warning

Framework7: wrong or not complete browserHistory configurati

Error message

Framework7: wrong or not complete browserHistory configuration, trying to guess browserHistoryRoot

What it means

Framework7's Router supports browserHistory mode, but only an incomplete configuration was given (browserHistory enabled without a separator or root). Since it cannot reliably derive the root from the URL, it warns and guesses browserHistoryRoot from location.pathname. This is a console.warn, not a thrown error, so routing continues with the guessed root.

Source

Thrown at src/core/modules/router/router-class.js:903

    let initialUrl = router.params.url;
    let documentUrl = location.href.split(location.origin)[1];

    let historyRestored;
    const { browserHistory, browserHistoryOnLoad, browserHistorySeparator } = router.params;
    let { browserHistoryRoot } = router.params;
    if (
      (window.cordova ||
        (window.Capacitor &&
          (window.Capacitor.isNative ||
            (window.Capacitor.isNativePlatform && window.Capacitor.isNativePlatform())))) &&
      browserHistory &&
      !browserHistorySeparator &&
      !browserHistoryRoot &&
      location.pathname.indexOf('index.html')
    ) {
      // eslint-disable-next-line
      console.warn(
        'Framework7: wrong or not complete browserHistory configuration, trying to guess browserHistoryRoot',
      );
      browserHistoryRoot = location.pathname.split('index.html')[0];
    }
    if (!browserHistory || !browserHistoryOnLoad) {
      if (!initialUrl) {
        initialUrl = documentUrl;
      }
      if (location.search && initialUrl.indexOf('?') < 0) {
        initialUrl += location.search;
      }
      if (location.hash && initialUrl.indexOf('#') < 0) {
        initialUrl += location.hash;
      }
    } else {
      if (browserHistoryRoot && documentUrl.indexOf(browserHistoryRoot) >= 0) {
        documentUrl = documentUrl.substring(
          documentUrl.indexOf(browserHistoryRoot) + browserHistoryRoot.length,

View on GitHub (pinned to 6557591266)

Solutions

1. Set browserHistoryRoot explicitly in the app/router params to the base path of the app (e.g. '/my-app/').
2. Or set browserHistorySeparator (e.g. '/') so the root can be derived without guessing.
3. If history integration is not needed, disable browserHistory (use default hash navigation).
4. Ensure the app is served at a URL whose root matches the configured history root.

Example fix

// before
new Framework7({ router: { browserHistory: true } });
// after
new Framework7({ router: { browserHistory: true, browserHistoryRoot: '/my-app/' } });

const p = new URLSearchParams(); // validate router params before app init
if (appParams.router && appParams.router.browserHistory && !appParams.router.browserHistorySeparator && !appParams.router.browserHistoryRoot) {
  appParams.router.browserHistoryRoot = location.pathname.split('index.html')[0];
}

function hasCompleteHistoryConfig(r) {
  return !r.browserHistory || Boolean(r.browserHistorySeparator || r.browserHistoryRoot);
}

When it happens

Trigger: Creating a Router/App with browserHistory: true but omitting both browserHistorySeparator and browserHistoryRoot, and the current pathname does not contain 'index.html' (the indexOf('index.html') check is truthy for any pathname not containing that string, and also for paths containing it only at position 0).

Common situations: App served from a path other than index.html (e.g. '/app/' or clean URLs) with history mode enabled; copy-pasted init options that set browserHistory without the matching root; deploying to a subdirectory without updating the router config.

Related errors

• Framework7: There is no View with "${anotherViewName}" name
• Framework7: TextEditor: wrong "buttons" parameter format
• Framework7: it is not allowed to use router methods on globa
• Framework7: "name" or "path" parameter is required
• Framework7: route with name "${name}" not found

AI-assisted analysis of framework7io/framework7@6557591266 (2026-09-02). Data as JSON: /api/errors/e21c68326ffd13c7. Report an issue: GitHub.