[Solution Guide] Solving the "set_page_config() can only be called once" Error in Streamlit Multipage Apps (v2)

Show the Community!
1

The Problem

When building multipage apps with Streamlit’s new st.Page and st.navigation API, you might encounter this error:

StreamlitSetPageConfigMustBeFirstCommandError: `set_page_config()` can only be called once per app page, and must be called as the first Streamlit command in your script.

This typically happens when:

  1. You have set_page_config() in multiple files
  2. Something is triggering Streamlit commands before your set_page_config() call
  3. You’re using the new navigation API incorrectly

The Solution

Here’s a working pattern for multipage apps using the new st.Page and st.navigation API:

import streamlit as st
# Import other libraries here
# ...

# CRITICAL: set_page_config MUST be the first Streamlit command
st.set_page_config(
    page_title="My App",
    page_icon="🔍",
    layout="wide",
    initial_sidebar_state="expanded",
    menu_items={
        'Get Help': 'https://example.com/help',
        'Report a bug': "https://example.com/bug",
        'About': "# My Amazing App"
    }
)

# Define page functions
def main_page():
    st.title("Main Page")
    # Your main page code here

# Define your pages
main_page = st.Page(main_page, title="Main", icon="🏠") ## Notice main_page here getting code from def above, not first_page.py! This is the critical point.
second_page = st.Page("second_page.py", title="Second Page", icon="📊")

# Create navigation
pages = {
    "Your App": [
        main_page,
        second_page,
    ]
}

pg = st.navigation(pages)
pg.run()

In your secondary page files (like second_page.py), do not include st.set_page_config(). For example:

# second_page.py
import streamlit as st

# NO set_page_config() here!

st.title("Second Page")
# Your second page code here

Common Pitfalls to Avoid

  1. Hidden Streamlit Commands: Make sure no Streamlit commands run before set_page_config(), including from imported modules.

  2. Decorators: Decorators like @st.cache_data or @st.experimental_fragment can trigger Streamlit commands. Place them after set_page_config().

  3. Multiple Config Calls: Only use set_page_config() in your main entry file, not in page files.

  4. Order Matters: The correct order is:

    • Import libraries
    • Call st.set_page_config() - don’t import current page! Notice
    • Define page functions
    • Create st.Page objects
    • Set up navigation
    • Call pg.run()

If You Still See Errors

If your app works but still shows the error at the bottom, try:

  1. Check Imports: Some imported modules might be using Streamlit commands.

  2. Try/Except Block: Wrap your set_page_config() in a try/except block:

    try:
    st.set_page_config(...)
except:
    pass  # Config already set

  3. Simplify: Start with a minimal app and add components gradually to identify what’s causing the issue.

Why This Works

The new multipage app API in Streamlit requires a single page configuration for the entire app. The entrypoint file acts as a router, and all pages share the same configuration. This is different from the older folder-based multipage approach where each page could have its own configuration.

Hope this helps others facing the same issue!

Feel free to modify this template to better fit your specific experience while removing any private information about your application.