You carefully wrote a System Instruction, configured the model to behave a certain way — and then it completely ignored you. Maybe it slipped back into a generic tone after a few turns, or never followed the language rules you specified. If you've been there, you're not alone.
System Instructions are the most powerful way to control Gemini's behavior through the API, but there are a handful of implementation pitfalls that make them silently fail. In almost every case I've seen, the problem isn't that the model is incapable of following instructions — it's that the instructions weren't delivered correctly. Here are the four patterns to check.
Pattern 1: Mixing System Instructions into the contents Array
This is the most common mistake. System Instructions must be passed as a separate system_instruction parameter during model initialization — not embedded inside contents as a user message.
import google.generativeai as genai
genai.configure(api_key="YOUR_API_KEY")
# ❌ Wrong: sending system instructions as a user message
model = genai.GenerativeModel("gemini-2.5-pro")
response = model.generate_content([
{"role": "user", "parts": ["You are a helpful assistant who only responds in pirate speak."]},
{"role": "model", "parts": ["Aye aye, captain\!"]},
{"role": "user", "parts": ["What's the weather like today?"]},
])
print(response.text)
# → Often returns normal English, not pirate speakThe correct approach is to set system_instruction when initializing GenerativeModel:
# ✅ Correct: pass as system_instruction parameter
model = genai.GenerativeModel(
model_name="gemini-2.5-pro",
system_instruction="You are a helpful assistant who always responds in pirate speak, no matter what the user asks."
)
response = model.generate_content("What's the weather like today?")
print(response.text)
# → "Arrr, the weather today be quite fine, matey\!"When using the REST API directly, use the systemInstruction field at the top level:
{
"systemInstruction": {
"parts": [{"text": "You are a helpful assistant who always responds in pirate speak."}]
},
"contents": [
{"role": "user", "parts": [{"text": "What's the weather like today?"}]}
]
}Pattern 2: System Instructions Drifting in Multi-Turn Conversations
This one is subtle. If you're using start_chat() with a history parameter and you've embedded your system instruction as a user message in the history, you'll often see the model follow it at first — then gradually stop as the conversation grows.
# ❌ Wrong: hiding system instructions inside chat history
chat = model.start_chat(history=[
{"role": "user", "parts": ["Always respond in under 100 words."]},
{"role": "model", "parts": ["Understood."]},
])
# This might work initially, but will break after several turns
response = chat.send_message("Explain how neural networks work.")The fix is simple: set your instruction in GenerativeModel and keep history clean.
# ✅ Correct: set system_instruction at model level
model = genai.GenerativeModel(
model_name="gemini-2.5-pro",
system_instruction="Keep all responses under 100 words. If a topic requires more detail, summarize the key point only."
)
chat = model.start_chat() # start with empty history — that's fine
response = chat.send_message("Explain how neural networks work.")
print(response.text)
# → Stays under 100 words across all turnsThink of history as the conversation log, not the rulebook. System Instructions belong in the model, not the conversation. For more on building reliable multi-turn experiences, see Gemini API Multi-Turn Chat Guide.
Pattern 3: Instructions That Are Too Long or Contain Contradictions
When System Instructions get long — say, more than a few hundred words — models tend to prioritize earlier instructions over later ones, and may skip conflicting rules entirely. I've seen this cause a lot of frustration because the model appears to be working correctly until you test the edge cases.
# ❌ Problematic: too many rules, some of which contradict each other
bad_instruction = """
You are a customer support agent. Follow all these rules:
1. Always be polite and use formal language
2. Use emojis frequently 😊 ← conflicts with "formal language"
3. Keep responses under 50 words
4. Always provide detailed explanations ← conflicts with rule 3
5. Never mention competitors
6. Always start with "Thank you for contacting us\!"
... (20 more rules)
"""Effective System Instructions are short, specific, and free of contradictions:
# ✅ Effective: focused, prioritized, and consistent
good_instruction = """
You are a customer support agent for an e-commerce platform.
Core rules:
- Keep responses under 150 words
- Use polite, professional language (no emojis unless the user uses them first)
Scope: Handle questions about orders, shipping, and returns only.
For technical issues, direct users to the engineering team.
Do not engage with competitor comparisons or pricing negotiations.
"""Aim for 200–400 words maximum. If you need more, consider splitting your use case into multiple specialized models rather than packing everything into one instruction. See System Instructions Guide for detailed writing tips.
Pattern 4: Thinking Mode Changes How Instructions Are Interpreted
If you're using Gemini 2.5 Pro with Thinking mode enabled, system instructions can behave differently from standard mode. Because the model is "thinking through" the problem before responding, it sometimes reframes or loosens formatting constraints.
import google.generativeai as genai
genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel(
model_name="gemini-2.5-pro",
system_instruction="Always respond using bullet points only."
)
# With Thinking mode enabled
response = model.generate_content(
"Explain quantum computing.",
generation_config=genai.GenerationConfig(
thinking_config={"thinking_budget": 10000}
)
)
print(response.text)
# → May return flowing prose instead of bullet pointsFor format-critical use cases with Thinking mode, use more explicit language in your instructions and reinforce the format requirement in the user message as well:
# ✅ More explicit instructions work better with Thinking mode
model = genai.GenerativeModel(
model_name="gemini-2.5-pro",
system_instruction="""
STRICT FORMAT REQUIREMENT — no exceptions:
- Every response must use bullet point format (lines starting with -)
- Do not use paragraphs, numbered lists, or any other format
- Each bullet must be 1-2 sentences maximum
"""
)
# Reinforce in the user message too
response = model.generate_content(
"Explain quantum computing. (Respond in bullet points only)"
)When Instructions Seem Completely Ignored
If none of the above patterns apply, check whether a safety filter is silently overriding your instructions. Some instruction types — particularly those asking the model to adopt persona that conflicts with Google's usage policies — get neutralized automatically without an obvious error.
response = model.generate_content("...")
print(response.candidates[0].finish_reason)
# SAFETY → safety filter is the cause
# STOP → normal completion; look at the other patterns aboveFor a full walkthrough of safety-related response blocking, see Fixing Safety Filter Blocked Responses in Gemini API.
Quick Diagnostic Checklist
When system instructions aren't working, run through this list in order:
First, verify that system_instruction is set in GenerativeModel() initialization — not in contents. Then check that no system-instruction-like text appears inside history or as user messages. Review the instructions for contradictions and trim anything past 400 words. Finally, check finish_reason on the response candidate to rule out safety filtering.
One last thing worth keeping in mind: System Instructions are best thought of as "high-priority context" rather than hard constraints. The model uses them as strong guidance, but isn't programmed to enforce them mechanically. Clear, concise, and contradiction-free instructions give you the best chance of consistent behavior — especially across longer conversations.
For broader error handling patterns, see Gemini API Error Handling and Troubleshooting.